0Pricing
OAuth2 & OpenID Connect Deep Dive · Lesson

OIDC Discovery Endpoint

Learn how the OIDC Discovery endpoint allows clients to retrieve all necessary OIDC configuration information programmatically.

OIDC Discovery Endpoint is a free OAuth2 & OpenID Connect Deep Dive lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the OAuth2 & OpenID Connect Deep Dive learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is OIDC Discovery?

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!

The Discovery Endpoint

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.

Finding the Discovery Document

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.

Key Fields: Issuer & JWKS URI

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.

Key Fields: Endpoints

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.

Key Fields: Capabilities

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.

Example Discovery Document

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

{
  "issuer": "https://example.com/openid",
  "authorization_endpoint": "https://example.com/openid/auth",
  "token_endpoint": "https://example.com/openid/token",
  "userinfo_endpoint": "https://example.com/openid/userinfo",
  "jwks_uri": "https://example.com/openid/jwks",
  "scopes_supported": [
    "openid",
    "profile",
    "email"
  ],
  "response_types_supported": [
    "code",
    "id_token",
    "token id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "refresh_token"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

How Clients Use Discovery

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.

Benefits of Discovery

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.

Test Your Knowledge

Which of the following fields in the OIDC Discovery document is used by a client to verify the signature of an ID Token?

Recap: OIDC Discovery

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.

Frequently asked questions

Is the “OIDC Discovery Endpoint” lesson free?

Yes — the full text of “OIDC Discovery Endpoint” is free to read here on the web, and the OAuth2 & OpenID Connect Deep Dive course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the OAuth2 & OpenID Connect Deep Dive course, upgrade to CoddyKit PRO.

What will I learn in “OIDC Discovery Endpoint”?

Learn how the OIDC Discovery endpoint allows clients to retrieve all necessary OIDC configuration information programmatically. You practise OAuth2 & OpenID Connect Deep Dive with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start OAuth2 & OpenID Connect Deep Dive?

No prior experience is required. OAuth2 & OpenID Connect Deep Dive on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “OIDC Discovery Endpoint” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this OAuth2 & OpenID Connect Deep Dive lesson?

Yes. Every OAuth2 & OpenID Connect Deep Dive lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Dynamic Client Registration
  2. OIDC Discovery Endpoint
  3. Session Management
  4. Claims Request and aggregated Claims
← Back to OAuth2 & OpenID Connect Deep Dive