Introduction
RFC 8414 lets an OAuth 2.0 authorization server publish its configuration as a JSON document, so a client can find the endpoints and learn the capabilities without being configured by hand. “By default, the well-known URI string used is
/.well-known/oauth-authorization-server”, and it is inserted into the issuer identifier between the host and the path (for the issuer https://example.com/issuer1 the document is at /.well-known/oauth-authorization-server/issuer1), which is unlike
OpenID Connect Discovery, where it is appended (RFC 8414 section 5 explains the difference, and the name openid-configuration that some applications use). A successful response is HTTP 200 with application/json. Clients that find an issuer that differs from the issuer
they started with “MUST NOT” use the data. The document is the metadata of the OpenID Provider too, with a few members each specification defines alone.
Structure
{
"issuer": "https://server.example.com",
"authorization_endpoint": "https://server.example.com/authorize",
"token_endpoint": "https://server.example.com/token",
"token_endpoint_auth_methods_supported": ["client_secret_basic", "private_key_jwt"],
"jwks_uri": "https://server.example.com/jwks.json",
"registration_endpoint": "https://server.example.com/register",
"scopes_supported": ["openid", "profile"],
"response_types_supported": ["code", "code token"]
}
| Status | Members (RFC 8414 section 2) |
|---|---|
| REQUIRED | issuer (a URL using the https scheme with no query or fragment component), response_types_supported. |
| REQUIRED, with exceptions | authorization_endpoint: unless no supported grant type uses it. token_endpoint: unless only the implicit grant type is supported. |
| RECOMMENDED | scopes_supported. |
| OPTIONAL | jwks_uri, registration_endpoint, response_modes_supported, grant_types_supported (default ["authorization_code","implicit"]), token_endpoint_auth_methods_supported,
token_endpoint_auth_signing_alg_values_supported (none MUST NOT be used), service_documentation, ui_locales_supported, op_policy_uri, op_tos_uri, revocation_endpoint and its two auth lists,
introspection_endpoint and its two auth lists, code_challenge_methods_supported (if omitted the server does not support PKCE), signed_metadata (a JWT asserting the values as a bundle; its values take precedence over plain JSON elements). |
| rules | “Claims with zero elements MUST be omitted from the response.” Other claims may be returned; some are defined by OpenID Connect Discovery. The names op_policy_uri, op_tos_uri and openid-configuration are not OpenID-specific here. |
In the explorer
A file named oauth-authorization-server or oauth-authorization-server.json opens here when it is a JSON object with a string issuer and at least four members that the two specifications define; the same check recognises an OpenID Provider document, but the file name decides which specification’s rules
apply. Any other file with these names opens as before. The tree labels each member with its status in RFC 8414 (members only OpenID Connect Discovery defines are labelled so); the Members tab lists what is present and the REQUIRED and RECOMMENDED members that are absent. A problem is a required member that is absent (with the two exceptions applied from
grant_types_supported and response_types_supported), an issuer that is not https or has a query or fragment, a member of the wrong type, an empty array, or none in a signing algorithm list. The issuer is not compared with the address the file came from. Of the public servers tried, 12 were claimed;
one (auth.openai.com) answered an HTML page.
Not described
Known, not yet covered
- Reference: the registries of client authentication methods and PKCE methods, the semantics of the algorithm lists, signature verification of
signed_metadata, and the security considerations (TLS, impersonation, publishing in a standard format) are named, not described. - Viewer: the two conditional endpoint rules are applied only from the grant and response types the file lists; the validation that the issuer equals the address the file was fetched from needs an address a file does not have.
- Viewer: a document of an authorization server used by an application with its own well-known name (RFC 8414 section 3) opens as JSON unless it is named as here.
Unknown
- Reference: metadata members defined by later RFCs (for example for MCP or resource indicators) are not in the text read and are labelled as not defined here.
Links
Reference
- RFC 8414 – OAuth 2.0 Authorization Server Metadata
- OpenID Connect Discovery 1.0 – the members the two documents share
- openid-configuration – the OpenID Provider form