What is OpenID Connect (OIDC) Discovery?
OpenID Connect (OIDC) Discovery, defined in OpenID Connect Discovery 1.0 , is a mechanism that allows clients to automatically discover the OpenID Provider’s endpoints and configuration. It is a modern approach to simplify the communication between clients and OpenID Providers .
OIDC Discovery has two main components:
- OpenID Provider issuer discovery: The client can discover the issuer’s location (URL) via WebFinger or an out-of-band document.
- OpenID Provider metadata: The client can retrieve and process the metadata document to learn about the OpenID Provider’s capabilities and endpoints.
How does OIDC Discovery work?
OpenID Provider issuer discovery
The OpenID Provider issuer is a unique identifier (usually the same as its URL) that clients can use to discover the OpenID Provider’s configuration. However, clients need to know the issuer’s location before they can retrieve the metadata document.
If the issuer’s location is already known, the client can skip to the next step. Otherwise, the client can use WebFinger to discover the issuer’s location. The necessary information for OIDC issuer discovery are:
host: Where the WebFinger service is hosted.resource: The email address or URL of the OpenID Provider.rel: The relation type, which should be set tohttp://openid.net/specs/connect/1.0/issuer.
For example, a user with the email address [email protected] is trying to discover the issuer’s location on example.com. The WebFinger request would look like this:
GET /.well-known/webfinger?resource=acct%3Afoo%40bar.com&
rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer HTTP/1.1
Host: example.com
The decoded resource parameter is acct:[email protected], and the rel parameter is http://openid.net/specs/connect/1.0/issuer.
OpenID Provider metadata
Once the client knows the issuer’s location, it can retrieve the metadata document from the well-known endpoint. The path to the metadata document is /.well-known/openid-configuration relative to the issuer’s URL.
For instance, if the issuer’s URL is https://oidc.example.com, the client can retrieve the metadata document from https://oidc.example.com/.well-known/openid-configuration. Here’s a non-normative example of the metadata response:
{
"issuer": "https://oidc.example.com",
"authorization_endpoint": "https://oidc.example.com/authorize",
"token_endpoint": "https://oidc.example.com/token",
//...
}
The metadata document contains many useful information about the OpenID Provider. Let’s highlight a few key fields:
issuer: The unique identifier of the OpenID Provider. It should be used for validating the tokens.authorization_endpoint: The URL to initiate the Authentication request .token_endpoint: The URL to send the Token request .jwks_uri: The URL to retrieve the JSON Web Key Set (JWKS) for Signing key validation.response_types_supported: The supported response types for the Authentication request .scopes_supported: The supported scopes for the Authentication request .claims_supported: The supported claims for the ID token .token_endpoint_auth_methods_supported: The supported client authentication methods for the Token request .
For an exhaustive list of metadata fields, please refer to the OpenID Connect Discovery 1.0 specification.