Skip to content
IAM Day by Day

OIDC Discovery

Self-Configuring Identity

Section titled “Self-Configuring Identity”

OIDC Discovery is the mechanism that allows a Service Provider (SP) to “Introduce” itself to an Identity Provider (IdP) with zero manual configuration. By standardizing a specific URL path—the .well-known/openid-configuration—OIDC makes it possible for applications to automatically discover every endpoint, cryptographic key, and security capability an IdP supports. This “Plug-and-Play” architecture is what enables global identity federation, allowing any modern library to integrate with providers like Okta, Google, or Azure AD simply by knowing their base “Issuer” URL.

DISCOVERY

Auto-Configuration
Core Mission
Universal Plug-and-Play. Eliminating the friction of manual endpoint configuration and public key management by providing a machine-readable "Map" of the Identity Provider's ecosystem.
Like a Universal Remote Control: In the past, to make a remote work with a TV, you had to manually look up and enter a secret four-digit code (Manual Endpoint Config). With OIDC Discovery, the TV broadcasts its own "Setup Page" on a standard frequency. The remote (The Application) simply listens to that frequency, reads the menu of available commands, and automatically configures itself to work perfectly with the TV.
Multi-Tenant SaaS / Dynamic Federation / Rapid App Onboarding

The Discovery Metadata Matrix

Section titled “The Discovery Metadata Matrix”

The discovery document is a JSON object that acts as the “Contract” between the application and the Auth Server.

Strategic Metadata breakdown

Section titled “Strategic Metadata breakdown”
categoryAttributesStrategic Value
Endpointsauthorization_endpoint, token_endpoint.Where to send the user and exchange codes.
Algorithmsid_token_signing_alg_values_supported.Ensuring cryptographic compatibility.
Keysjwks_uri.Where to fetch public keys for signature verification.
Capabilitiesscopes_supported, grant_types_supported.Knowing which features the IdP allows.

The Discovery Handshake

Section titled “The Discovery Handshake”

Discovery occurs once at application startup or periodically to refresh the provider’s technical state.

sequenceDiagram
    participant App as Client Application
    participant IdP as Identity Provider
    
    App->>IdP: GET /.well-known/openid-configuration
    IdP-->>App: JSON Metadata (Endpoints, Keys, etc.)
    App->>IdP: GET /jwks (Public Keys)
    IdP-->>App: JWK Set (RSA/EC Keys)
    App->>App: Cache Metadata & Start System
1

Initiate Lookup

The application takes the IdP's base URL (The Issuer) and appends the standard path. For example: `https://auth.company.com/.well-known/openid-configuration`. It performs a simple GET request to fetch the metadata.

2

Ingest & Configure

The app's OIDC library parses the JSON. It automatically maps its internal client settings to the IdP's specific URLs for authorization, token exchange, and user profile retrieval.

3

Fetch & Rotate Keys

The library uses the `jwks_uri` found in the metadata to download the current public keys. These keys are used to verify the signatures of incoming ID Tokens, ensuring they were truly issued by the trusted IdP.

Technical Discovery Implementation

Section titled “Technical Discovery Implementation”

Modern identity libraries require only the “Issuer” string to perform a full system bootstrap.

Configuration Discovery (Node.js Example)

Section titled “Configuration Discovery (Node.js Example)”
// Simplified OIDC Client Bootstrap via Discovery
import { Issuer } from 'openid-client';


async function bootstrapIdP(issuerUrl) {
    // 1. Discover all endpoints and capabilities
    const companyIdP = await Issuer.discover(issuerUrl);


    // 2. Initialize Client using discovered metadata
    const client = new companyIdP.Client({
        client_id: 'my_app_id',
        client_secret: 'my_app_secret',
        redirect_uris: ['https://app.example.com/callback'],
        response_types: ['code']
    });


    return client;
}

OIDC Implementation Guides

Section titled “OIDC Implementation Guides”

Master the technical details of dynamic identity provider configuration.

OIDC Overview

Strategic foundational principles for identity layering and federated authentication.

OIDC Flows

Using discovered endpoints to implement Authorization Code and Hybrid flows.

Key Management (JWKS)

Strategies for handling public key rotation and cryptographic signature verification.

IdP Selection (HRD)

Routing users to the correct discovery endpoint based on their email or domain.

Next Steps

Section titled “Next Steps”