OAuth 2.0 Dynamic Client Registration Protocol
Extracted elements (30)
Software statements and initial access tokens serve complementary but distinct purposes: a software statement attests to the identity and properties of client software (who the software is), while an initial access token authorizes use of the registration endpoint (permission to register). An authorization server MUST consider both together when evaluating a registration request.
The 'software_id' is assigned by the client developer and SHOULD remain stable across all instances and versions of a given software package, while 'client_id' is server-issued and SHOULD vary per instance. This separation allows authorization servers to correlate different deployments of the same software without conflating software identity with registration identity.
Use of 'jwks_uri' is preferred over the inline 'jwks' parameter because it allows for easier key rotation without requiring re-registration. The inline 'jwks' is intended only for clients that cannot host public URLs, such as native clients.
The 'grant_types' and 'response_types' values are correlated: 'authorization_code' implies 'code', 'implicit' implies 'token', while 'password', 'client_credentials', 'refresh_token', and JWT/SAML bearer grant types imply no response type. Servers SHOULD prevent clients from registering inconsistent combinations.
This specification generalizes the registration mechanisms from OpenID Connect Dynamic Client Registration 1.0 and UMA Profile of OAuth 2.0 in a compatible manner, and is applicable to a wider set of OAuth 2.0 use cases.
A software statement presented to an authorization server MUST be digitally signed or MACed using JSON Web Signature (JWS) and MUST contain an 'iss' (issuer) claim. It is RECOMMENDED that software statements be signed using the 'RS256' algorithm.
For clients using redirect-based grant types such as 'authorization_code' and 'implicit', authorization servers MUST require clients to register their redirection URI values. Registered redirection URI values MUST be a TLS-protected remote site, a localhost HTTP URI, or a non-HTTP application-specific URL.
If a software statement was used in the registration, its value MUST be returned unmodified in the response using the 'software_statement' member name. Client metadata elements from the software statement MUST also be returned as top-level values in the registration response.
The authorization server MUST ignore any client metadata sent by the client that it does not understand, silently removing unknown metadata from the client's registration record during processing.
The authorization server MUST require the use of a transport-layer security mechanism when sending requests to the registration endpoint. The server MUST support TLS 1.2 and the client MUST perform a TLS/SSL server certificate check per RFC 6125.
The authorization server MUST return all registered metadata about a client in the registration response, including any fields provisioned by the authorization server itself. The response MUST use HTTP 201 Created with content type 'application/json'.
The authorization server MUST treat all client metadata as self-asserted unless the metadata is contained within a trusted software statement. The server MUST take appropriate steps to mitigate impersonation risks.
The client registration endpoint MUST accept HTTP POST messages with request parameters encoded in the entity body using the 'application/json' format and MUST be protected by a transport-layer security mechanism.
The 'jwks_uri' and 'jwks' parameters MUST NOT both be present in the same request or response.
When a software statement is trusted by the authorization server, the value of a claim in the software statement MUST take precedence over the same client metadata name conveyed in the plain JSON request body.
For native applications installed on a single device, per-instance client identifiers could be uniquely tracked across OAuth 2.0 transactions. Clients are forbidden from creating their own client identifiers to prevent cross-server tracking via colluding authorization servers.
The 'contacts' field contains developer contact information that will be visible to authorization server administrators and potentially end-users. Developers should consider using a dedicated support address rather than personal addresses to avoid unnecessary personal data exposure.
A Software Statement is a JWT that asserts metadata values about client software as a signed bundle. It is typically distributed with all instances of a client application and may be issued by the client developer or a third-party organization.
Client metadata fields defined for registration include: redirect_uris, token_endpoint_auth_method, grant_types, response_types, client_name, client_uri, logo_uri, scope, contacts, tos_uri, policy_uri, jwks_uri, jwks, software_id, and software_version. All fields are OPTIONAL unless stated otherwise.
The Client Information Response includes required 'client_id' (unique identifier), optional 'client_secret', optional 'client_id_issued_at' (Unix timestamp), and 'client_secret_expires_at' (REQUIRED if client_secret is issued; 0 means no expiration).
The client registration endpoint may optionally require an Initial Access Token — an OAuth 2.0 access token issued to a developer or client — to authorize calls to the registration endpoint and limit registration to previously authorized parties.
The Client Registration Error Response returns HTTP 400 with a JSON body containing a required 'error' string and optional 'error_description'. Defined error codes are: invalid_redirect_uri, invalid_client_metadata, invalid_software_statement, and unapproved_software_statement.
This specification establishes the 'OAuth Dynamic Client Registration Metadata' registry with Specification Required policy. Initial entries include: redirect_uris, token_endpoint_auth_method, grant_types, response_types, client_name, client_uri, logo_uri, scope, contacts, tos_uri, policy_uri, jwks_uri, jwks, software_id, software_version, client_id, client_secret, client_id_issued_at, and client_secret_expires_at.
This specification establishes the 'OAuth Token Endpoint Authentication Methods' registry with Specification Required policy. Initial entries are: 'none' (public client, no secret), 'client_secret_post' (HTTP POST parameters), and 'client_secret_basic' (HTTP Basic authentication, the default).
An authorization server SHOULD NOT issue the same client secret to multiple instances of a registered client, even if they share a client identifier, to prevent secret leakage and client impersonation.
Authorization servers supporting open registration SHOULD check that logo_uri, tos_uri, client_uri, and policy_uri share the same host and scheme as redirect_uris, and that all URIs resolve to valid web pages. Servers SHOULD protect users from malicious content at these URLs, for example by running malware scanning before presenting links.
If a server receives a registration for a client sharing the same 'software_id' and 'software_version' as an existing registration and does not expect multiple simultaneous instances, it SHOULD treat the new registration as suspect and reject it to prevent impersonation.
Human-readable client metadata fields (client_name, tos_uri, policy_uri, logo_uri, client_uri) MAY be internationalized by appending a BCP 47 language tag delimited by '#' to the member name, e.g., 'client_name#ja-Jpan-JP'.
The client registration request is an HTTP POST with Content-Type 'application/json'. The body is a JSON object with client metadata fields as top-level members. An optional Initial Access Token is carried as an OAuth 2.0 Bearer Token in the Authorization header.
The 'software_statement' field in a registration request is a string containing the entire signed JWT. The 'client_id_issued_at' and 'client_secret_expires_at' fields are integer seconds since 1970-01-01T00:00:00Z (Unix epoch).