Chapter 6: Discovery and Metadata — How Clients and Providers Find Each Other

This is Part 6 of a chapter-by-chapter walkthrough of my book OpenID: Modern Identity for Developers and Architects. In the previous chapter we dissected tokens themselves. Chapter 6 is about the connective tissue — the metadata and discovery machinery that lets a client and a provider meet for the first time and immediately agree on how to talk.

6.1 — .well-known/openid-configuration: The Document That Makes Everything Portable

Every conformant OpenID Provider publishes a discovery document at a predictable URL: https://provider.example.com/.well-known/openid-configuration. One HTTPS GET returns a JSON document describing everything a client needs to configure itself — endpoints, supported scopes, response types, grant types, signing algorithms, and more.

This single convention is why you can plug a new OpenID Provider into a well-written RP with nothing but the issuer URL. No hand-crafted endpoint lists, no vendor-specific configuration files. The client reads the document, learns the provider, and proceeds.

6.2 — Provider Metadata: What to Read, What to Trust

The discovery document is not a formality. It is the source of truth for several decisions your RP will make on every login:

• issuer — the unique identifier you'll later compare against the iss claim in every token.
• authorization_endpoint, token_endpoint, userinfo_endpoint — where the flow happens.
• jwks_uri — where you'll fetch public keys for signature validation (more on this in 6.3).
• response_types_supported, grant_types_supported — what the provider will actually honor.
• subject_types_supported — public (same sub for all clients) vs. pairwise (per-client sub for privacy).
• id_token_signing_alg_values_supported — the algorithms you need to accept.

Chapter 6 walks through the fields you can safely skim and the ones that deserve an assertion in your startup code. The issuer in particular is not just a label; it's a trust boundary.

6.3 — JWKS: Keys Without the Configuration Hell

The JSON Web Key Set exposed at jwks_uri is how RPs get the public keys they need to validate token signatures. Each entry carries a kid (key ID) so tokens can specify which key signed them, and each entry contains the key material itself in a standardized format.

The operational upshot is key rotation without downtime. A provider can publish a new signing key alongside the old one, start signing tokens with the new key, and gradually retire the old one — all while every in-flight token remains valid. Your RP's only job is to cache the JWKS, refresh it on a schedule, and refresh opportunistically when it sees a kid it doesn't recognize.

6.4 — Dynamic Client Registration: Identity That Provisions Itself

Dynamic Client Registration (DCR) lets applications register themselves with an OpenID Provider at runtime, over HTTP, rather than via a human-completed admin form. The client POSTs its metadata — redirect URIs, desired response types, grant types, scopes — to the registration_endpoint, and the provider returns a fresh client_id and (for confidential clients) a client_secret.

DCR is the thing that makes a few modern patterns tractable at all:

• Multi-tenant SaaS where each tenant needs its own OIDC client record.
• Ephemeral services in a microservices or serverless environment.
• Third-party integrations where partners shouldn't have to wait on your ops team to provision access.
• AI agents — which is why Chapter 22 returns to DCR for ephemeral agent identity.

The tradeoff is abuse. Open (unauthenticated) DCR requires rate limiting, redirect-URI validation, and careful scope gating; authenticated DCR is harder to automate but much safer. Most real deployments use authenticated DCR with an initial access token that the operator hands out once.

What Chapter 6 Sets Up

After Chapter 6 you should be able to start a new RP against an unfamiliar OpenID Provider with nothing but the issuer URL, explain why jwks_uri matters more than any individual key, and know when DCR is a shortcut and when it's a footgun. These are the mechanisms that make OIDC feel like a single protocol rather than 400 incompatible dialects.

Next up — Chapter 7: Your First OpenID Application. Enough theory. We walk through building an actual minimal web login — the OIDC handshake end to end, state and nonce, redirect handling, session creation, and the full spectrum of logout flows (front-channel, back-channel, universal). Chapter 7 is the first time we go hands-on.