OIDC Discovery Endpoint

Imagine you're building an application that needs to connect to an OpenID Provider (IdP) like Google or Auth0. How do you know its authorization URL, token URL, or how to get its public keys?

Manually configuring these details for every IdP is tedious and error-prone. This is where OIDC Discovery comes in!

OIDC Discovery provides a standardized way for clients to find all the necessary configuration information of an OpenID Provider.

Instead of hardcoding URLs, your client application can fetch a single JSON document from a well-known URL. This document contains all the endpoints and capabilities of the IdP.

Clients typically access the OIDC Discovery document at a specific, standardized URL:

• Base URL of the OpenID Provider
• Followed by /.well-known/openid-configuration

For example, if your IdP's base URL is https://accounts.example.com, the discovery endpoint would be https://accounts.example.com/.well-known/openid-configuration.

The discovery document is a JSON object with many fields. Two crucial ones are:

• issuer: A URL that uniquely identifies the OpenID Provider. It must match the iss claim in ID Tokens.
• jwks_uri: The URL of the JSON Web Key Set (JWKS) document. This document contains the public keys used by the IdP to sign ID Tokens, allowing your client to verify their authenticity.

The discovery document lists the various endpoints your client will interact with:

• authorization_endpoint: Where the user is redirected to grant consent.
• token_endpoint: Where the client exchanges the authorization code for access and ID tokens.
• userinfo_endpoint: Where the client can request user profile information after obtaining an access token.
• end_session_endpoint: (Optional) Where the client can redirect the user to log out from the IdP.

The document also declares the IdP's capabilities:

• scopes_supported: A list of the OAuth 2.0 scope values that this IdP supports.
• response_types_supported: A list of the OAuth 2.0 response_type values that this IdP supports.
• grant_types_supported: (Optional) A list of the OAuth 2.0 grant_type values that this IdP supports.

These help your client understand what features are available.

Here's a simplified example of what an OIDC Discovery document might look like:

A client application can perform OIDC Discovery by:

1. Fetching the JSON document from the /.well-known/openid-configuration endpoint.
2. Parsing the JSON to extract the necessary URLs and capabilities.
3. Using these dynamically discovered values to construct authorization requests, exchange tokens, and validate ID Tokens.

This makes client integration much more robust and future-proof.

Using OIDC Discovery offers several advantages:

• Reduced Configuration: Clients don't need to hardcode IdP endpoints.
• Increased Flexibility: IdPs can change endpoint URLs without breaking clients.
• Enhanced Security: Clients can easily find the jwks_uri to verify ID Token signatures.
• Interoperability: Promotes a standardized way for clients to interact with any OIDC-compliant IdP.

We've learned that OIDC Discovery provides a standardized way for clients to find an OpenID Provider's configuration.

• Clients access a well-known /.well-known/openid-configuration endpoint.
• The returned JSON document contains essential URLs (authorization, token, userinfo, jwks) and capabilities (scopes, response types).
• This automation simplifies client setup, improves flexibility, and enhances security by providing necessary public keys for token validation.