GitHub Designed by Logto

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 to http://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:

For an exhaustive list of metadata fields, please refer to the OpenID Connect Discovery 1.0 specification.

See also