Dynamic client registration#

Requirements: APP-016, APP-017, ADV-003 (RFC 7591, RFC 7592). Code: internal/application/dcr.go, internal/httpapi/dcr.go, migration 0052. Tests: TestDynamicClientRegistration (tests/e2e/dcr_test.go) and TestDynamicClientRegistrationBounds (tests/e2e/dcr_bounds_test.go).

Dynamic registration lets software register its own OAuth client at /realms/{realm}/oauth/register instead of asking an administrator to create it. It is off by default. A realm turns it on, and an administrator then decides who may register: holders of an initial access token, or anyone (open registration, always held for approval). Registered clients are third-party clients that ask users for consent; they never get privileged scopes, first-party status, offline access or administrative audiences.

Enabling it#

Realm policy client_registration (PUT /api/v1/realms/{realm}/settings, or a configuration import):

Discovery advertises registration_endpoint (I/oauth/register) while enabled is set, whatever open says.

Initial access tokens#

An initial access token (pa_iat_...) is the registration authority an administrator hands to a developer or a partner (ADV-003). Paths are relative to /api/v1/realms/{realm}:

POST /api/v1/realms/main/client-registration-tokens
{
  "description": "Partner integrations, Q4",
  "allowed_scopes": [{"resource_id": "res_orders", "scopes": ["orders:read"]}],
  "project_id": "prj_...",
  "max_uses": 5,
  "expires_in_seconds": 604800
}

Registering a client#

curl -sS https://id.example.com/realms/main/oauth/register \
  -H "Authorization: Bearer pa_iat_..." -H "Content-Type: application/json" \
  -d '{"client_name": "Example partner app",
       "redirect_uris": ["https://partner.example.net/callback"],
       "grant_types": ["authorization_code", "refresh_token"],
       "scope": "openid email orders:read"}'

The Authorization header carries an initial access token, or nothing when the realm sets open. A missing token (without open), or a token that is unknown, expired, revoked or used up (also with open), is 401 (error: invalid_token, WWW-Authenticate: Bearer error="invalid_token"). The body must be application/json of at most 64 KiB.

Metadata. Unknown members are ignored (RFC 7591 §2), including the URL-valued ones ProudAuth does not support: sector_identifier_uri, request_uris, initiate_login_uri and backchannel_logout_uri are neither stored nor fetched, and subject_type is ignored (a pairwise subject and a back-channel logout URI are set only by an administrator; a request_uri is only ever a pushed authorization request reference, never fetched). Accepted:

Errors are RFC 7591 JSON (error, error_description) with status 400:

Other failures are problem details: 404 when registration is disabled or the realm is not active, 429 and 503 (budgets, below).

What the client becomes. Every registered client is created with:

• client ID app_...; security profile third_party, consent_mode: required, not first-party, subject_type: public, no offline access (offline_access is refused at authorization), and dynamically_registered: true in the client view;
• UserInfo scopes: open_scopes ∩ the requested scopes, or all of open_scopes when scope is empty;
• with an initial access token, also a resource grant (subject type user, no exchange policy) for each allowed resource: its allowed scopes ∩ the requested ones, or all of them when scope is empty;
• the token's project_id, if it names one.

Requested scopes outside these sets are dropped without error; the response's scope lists what was granted (it can be empty).

Budgets. 20 registration requests per hour per client address and 500 per hour per realm, in fixed hourly windows; every POST counts, also refused ones. Beyond them 429 with Retry-After. The budgets fail closed: when the limiter is unavailable the answer is 503.

Response 201:

{"client_id": "app_...", "client_secret": "pa_cs_...", "client_secret_expires_at": 0,
 "client_id_issued_at": 1791590400,
 "registration_access_token": "pa_rat_...",
 "registration_client_uri": "https://id.example.com/realms/main/oauth/register/app_...",
 "scope": "openid email orders:read",
 "client_name": "Example partner app",
 "redirect_uris": ["https://partner.example.net/callback"],
 "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"],
 "token_endpoint_auth_method": "client_secret_basic",
 "proudauth_approval_state": "approved", "proudauth_client_state": "active"}

The response also repeats the other registered metadata (not jwks). client_secret is present only for client_secret_basic and client_secret_post (client_secret_expires_at: 0: it does not expire). Keep the registration access token: it is the only credential for managing the registration.

Approval#

A registration without an initial access token, or any registration while require_approval is set, is created with proudauth_approval_state: pending and the client suspended: it can do nothing until an administrator decides (its registrant can still read and update it).

{client} is the client's internal reference (client_ref). Deciding a registration that is not pending is 409, an unknown one 404. The address the registration came from is kept with it for review. Only the approval activates a pending registration: POST /clients/{client}/reactivate (and the emergency control's enable for the client) answers 409 ("the client's dynamic registration is pending approval ...") while the registration is pending.

Managing a registration (RFC 7592)#

registration_client_uri (/realms/{realm}/oauth/register/{client_id}) accepts only Authorization: Bearer <registration access token> of that client (pa_rat_..., one active per client). Anything else, including another client's token, an administrator's access token, a token already replaced by an update, or any token of a decommissioned client, is 401 invalid_token.

PUT with the extension member rotate_secret: true also returns a new client_secret (only for client_secret_basic and client_secret_post clients; otherwise the member is ignored). The previous secrets stay valid for at most one hour. limits.client_secrets_max (3 by default) bounds the secrets that are still valid; secrets past their expiry do not count. A rotation beyond it (for example a third rotation within the hour) is 409 (problem details) and changes nothing: the metadata stays as it was, no secret is issued, and the registration access token presented stays valid; retry once the older secrets expired, or have an administrator revoke one (DELETE /clients/{client}/credentials/{id}).

A PUT replaces only the metadata a registrant registers: client_name, redirect_uris, post_logout_redirect_uris, grant_types, token_endpoint_auth_method (within the same client type), contacts, software_id, software_version, and the protocol options (client_uri, logo_uri, policy_uri, tos_uri, front-channel logout, response signing and encryption, tls_client_certificate_bound_access_tokens). Settings an administrator controls through the client API are kept, not reset: description, security_profile, first_party, consent_mode, consent_terms_version, allow_offline_access, allow_remember_me, default_resource_id, environment, project and owner, subject_type and sector_identifier, login_ui_url, backchannel_logout_uri, allowed_origins, claim mappings and token_policy. A registrant's change that conflicts with them is refused like any invalid metadata: for example, with a pairwise subject_type, redirect URIs outside the sector are 400 invalid_client_metadata. Keys registered with jwks at registration cannot be changed through PUT.

Administrators see and manage dynamically registered clients through the ordinary client API as well (dynamically_registered: true): they can change grants, issue or revoke credentials, suspend or decommission them.

Audit#

client.registered (actor type registration, ID the initial access token's ID or open), client.registration.updated, .approved and .rejected; client_registration.initial_token.created and .revoked; plus the ordinary events of the changes they cause (client.created, client.resource_grant.set, client.updated, client.credential.issued, client.active, client.decommissioned). All are in category configuration.

Limits and known issues#

• No software statements, no jwks_uri, no fetching of client metadata URLs.
• Registered clients cannot use client credentials, device code, token exchange, jwt-bearer, mutual-TLS client authentication or the privileged, high_assurance and fapi2 profiles, and cannot be first-party or skip consent.
• Registration access tokens do not expire; they rotate on every update and end with the client. The management endpoints have no rate limit.
• contacts are not verified, so they are never used as mail recipients; they still count as named contacts in the ownership report.
• Approved registered clients appear in the configuration export as ordinary clients (without the dynamically_registered marker); importing such a document elsewhere creates ordinary clients without a registration. Initial access tokens and registrations are not exported.

Threats and mitigations: system threat model (public protocol endpoints).