Skip to main content

3. Obtaining Authorization Server Metadata

Authorization servers supporting metadata MUST make a JSON document containing metadata as specified in Section 2 available at a path formed by inserting a well-known URI string into the authorization server's issuer identifier between the host component and the path component (if any). By default, the well-known URI string used is /.well-known/oauth-authorization-server. This path MUST use the "https" scheme. The syntax and semantics of ".well-known" are defined in RFC 5785 [RFC5785]. The well-known URI suffix used MUST be registered in the IANA "Well-Known URIs" registry [IANA.well-known].

Different applications utilizing OAuth authorization servers in application-specific ways MAY define and register different well-known URI suffixes used for publishing authorization server metadata used by those applications. For example, if an example application uses OAuth authorization servers in an example-specific way and needs to publish example-specific metadata values, it might register and use the "example-configuration" URI suffix and publish the metadata document by inserting /.well-known/example-configuration between the host and path components of the authorization server's issuer identifier. Alternatively, many such applications will use the default well-known URI string /.well-known/oauth-authorization-server, which is the right choice for general-purpose OAuth authorization servers, and not register an application-specific one.

OAuth 2.0 applications using this specification MUST specify which well-known URI suffix they will use for this purpose. The same authorization server MAY choose to publish its metadata at multiple well-known locations derived from its issuer identifier, for example, publishing it at both /.well-known/example-configuration and /.well-known/oauth-authorization-server.

Some OAuth applications will choose to use the well-known URI suffix "openid-configuration". As described in Section 5, despite the identifier /.well-known/openid-configuration appearing to be OpenID-specific, its usage in this specification is actually referring to a general OAuth 2.0 feature and is not specific to OpenID Connect.

3.1. Authorization Server Metadata Request​

The authorization server metadata document MUST be queried using an HTTP "GET" request at the previously specified path.

When the issuer identifier is https://example.com and the well-known URI suffix is "oauth-authorization-server", the client will make the following request to obtain the metadata, since the issuer identifier contains no path component:

GET /.well-known/oauth-authorization-server HTTP/1.1
Host: example.com

If the issuer identifier value contains a path component, any terminating "/" MUST be removed before inserting /.well-known/ and the well-known URI suffix between the host and path components. When the issuer identifier is https://example.com/issuer1 and the well-known URI suffix is "oauth-authorization-server", the client will make the following request to obtain the metadata, since the issuer identifier contains a path component:

GET /.well-known/oauth-authorization-server/issuer1 HTTP/1.1
Host: example.com

The use of path components enables supporting multiple issuers per host. This is required in some multi-tenant hosting configurations. This usage of ".well-known" is for supporting multiple issuers per host; unlike its usage in RFC 5785 [RFC5785], it does not provide general information about the host.

3.2. Authorization Server Metadata Response​

The response is a set of claims about the authorization server's configuration, including all necessary endpoints and public key location information. A successful response MUST use the 200 OK HTTP status code and return a JSON object using the "application/json" content type that contains a set of claims as its members that are a subset of the metadata values defined in Section 2. Other claims MAY also be returned.

Claims that return multiple values are represented as JSON arrays. Claims with zero elements MUST be omitted from the response.

An error response uses the applicable HTTP status code value.

The following is a non-normative example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
 "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"],
 "token_endpoint_auth_signing_alg_values_supported":
   ["RS256", "ES256"],
 "userinfo_endpoint":
   "https://server.example.com/userinfo",
 "jwks_uri":
   "https://server.example.com/jwks.json",
 "registration_endpoint":
   "https://server.example.com/register",
 "scopes_supported":
   ["openid", "profile", "email", "address",
    "phone", "offline_access"],
 "response_types_supported":
   ["code", "code token"],
 "service_documentation":
   "http://server.example.com/service_documentation.html",
 "ui_locales_supported":
   ["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"]
}

3.3. Authorization Server Metadata Validation​

The "issuer" value returned MUST be identical to the authorization server's issuer identifier value into which the well-known URI string was inserted to create the URL used to retrieve the metadata. If these values are not identical, the data contained in the response MUST NOT be used.

Last updated on