OAuth 2.0 Authorization Server Metadata
Extracted elements (30)
Inserting the well-known URI string before the path component (rather than appending it) allows a single host to support multiple issuers via path components, which is required for multi-tenant hosting configurations. This is the key semantic difference from RFC 5785's original 'host-level' well-known URI concept.
RFC 8414 generalizes OpenID Connect Discovery 1.0's metadata format to be applicable to a wider set of OAuth 2.0 use cases, intentionally paralleling how RFC 7591 generalized OpenID Connect Dynamic Client Registration. This allows OAuth implementations to adopt a standard discovery mechanism without requiring OpenID Connect.
The issuer identifier is used to prevent authorization server mix-up attacks. By requiring that the 'issuer' value in the metadata response exactly match the URL used to retrieve it, clients can verify they are talking to the intended authorization server and not a confused or malicious substitute.
During transition from OpenID Connect Discovery 1.0 deployments, applications should first attempt the RFC 8414 URL transformation and only fall back to the OIDC Discovery transformation if that fails. This fallback behavior is only needed when the well-known URI suffix is 'openid-configuration'.
RFC 8414 and OpenID Connect Discovery 1.0 differ in how they construct the metadata URL when the issuer contains a path component. OIDC Discovery appends the well-known string to the issuer (e.g., 'https://example.com/issuer1/.well-known/openid-configuration'), while RFC 8414 inserts it before the path (e.g., 'https://example.com/.well-known/openid-configuration/issuer1').
The identifiers '/.well-known/openid-configuration', 'op_policy_uri', and 'op_tos_uri' appear OpenID-specific but are reused in RFC 8414 to refer to general OAuth 2.0 features not specific to OpenID Connect, for backwards compatibility.
An OAuth 2.0 application using this specification MUST specify what well-known URI suffix it will use. The well-known URI suffix used MUST be registered in the IANA 'Well-Known URIs' registry.
Authorization servers supporting metadata MUST make a JSON document available at a path formed by inserting the well-known URI string '/.well-known/oauth-authorization-server' into the issuer identifier between the host component and the path component. This path MUST use the 'https' scheme.
Claims with zero elements MUST be omitted from the metadata response. A successful metadata response MUST use the 200 OK HTTP status code and return a JSON object using the 'application/json' content type.
Comparisons between JSON strings and other Unicode strings MUST be performed as Unicode code-point-to-code-point equality comparisons. Unicode Normalization MUST NOT be applied at any point to either string being compared.
Implementations MUST support TLS. The authorization server MUST support TLS version 1.2 and MAY support additional TLS mechanisms. When using TLS, the client MUST perform a TLS/SSL server certificate check per RFC 6125.
The 'issuer' metadata field is REQUIRED and must be a URL using the 'https' scheme with no query or fragment components. The 'response_types_supported' field is also REQUIRED as a JSON array of OAuth 2.0 response_type values.
The 'issuer' value returned in the metadata response MUST be identical to the authorization server's issuer identifier value used as the prefix for the metadata request URL. If these values are not identical, the data contained in the response MUST NOT be used.
The jwks_uri URL MUST use the 'https' scheme. When both signing and encryption keys are available in the JWK Set, a 'use' (public key use) parameter value is REQUIRED for all keys to indicate each key's intended usage.
The signed_metadata JWT MUST be digitally signed or MACed using JWS and MUST contain an 'iss' (issuer) claim. If a consumer supports signed metadata, metadata values in the signed metadata MUST take precedence over corresponding values in plain JSON elements.
The 'token_endpoint_auth_signing_alg_values_supported' metadata entry MUST be present if 'private_key_jwt' or 'client_secret_jwt' authentication methods are specified. The value 'none' MUST NOT be used for signing algorithm values.
TLS certificate checking MUST be performed by the client when making an authorization server metadata request. Checking that the server certificate is valid for the issuer identifier URL prevents man-in-the-middle and DNS-based attacks.
The authorization server metadata document is a JSON object served at a well-known HTTPS endpoint. Required fields include 'issuer' and 'response_types_supported'; optional fields include 'authorization_endpoint', 'token_endpoint', 'jwks_uri', 'scopes_supported', 'grant_types_supported', and many others defining server capabilities.
The 'code_challenge_methods_supported' field is an optional JSON array listing PKCE code challenge methods (RFC 7636) supported by the authorization server. If omitted, the server does not support PKCE.
The 'introspection_endpoint_auth_methods_supported' field accepts values from both the IANA 'OAuth Token Endpoint Authentication Methods' registry and the 'OAuth Access Token Types' registry, which must remain mutually exclusive to avoid ambiguity.
The 'signed_metadata' field is an optional JWT containing metadata values about the authorization server as claims. It enables the issuer to vouch for the validity of the data, analogous to the Software Statement in OAuth Dynamic Client Registration.
This specification establishes the IANA 'OAuth Authorization Server Metadata' registry for OAuth 2.0 authorization server metadata names, with 'Specification Required' registration policy. Initial contents include 22 metadata names such as 'issuer', 'authorization_endpoint', 'token_endpoint', 'jwks_uri', 'signed_metadata', and 'code_challenge_methods_supported'.
This specification registers the well-known URI suffix 'oauth-authorization-server' in the IANA 'Well-Known URIs' registry (established by RFC 5785), with IESG as change controller.
This specification updates registration instructions for the IANA 'OAuth Access Token Types' and 'OAuth Token Endpoint Authentication Methods' registries to require that Designated Experts reject registration requests in one registry for values already occurring in the other, keeping them mutually exclusive.
An attacker may attempt to impersonate an authorization server by publishing a metadata document with the victim server's 'issuer' claim but the attacker's own endpoints and keys. Clients MUST validate that the 'issuer' in the response exactly matches the issuer identifier used to construct the metadata URL.
Confidentiality protection MUST be applied using TLS with a ciphersuite providing both confidentiality and integrity, to protect against information disclosure and tampering of the metadata document in transit.
If an inappropriate protected resource is used by the client, an attacker may be able to act as a man-in-the-middle proxy to a valid protected resource undetected. Determining appropriate authorization server / protected resource associations is application-dependent and out of scope.
Publishing metadata in a standard format makes it easier for both legitimate clients and attackers to use the authorization server. The same defenses against attacks should be applied regardless of whether metadata is published in a standard or ad hoc format.
The metadata document is retrieved via an HTTP GET request. For an issuer with no path component (e.g., 'https://example.com'), the metadata URL is 'https://example.com/.well-known/oauth-authorization-server'. For an issuer with a path (e.g., 'https://example.com/issuer1'), the well-known string is inserted before the path: 'https://example.com/.well-known/oauth-authorization-server/issuer1'.
The metadata response is a JSON object with 'application/json' content type and HTTP 200 status. Claims returning multiple values are JSON arrays; claims with zero elements must be omitted. The 'signed_metadata' value is a compact-serialized JWS string.