Encrypt Online
Theme

Certificates & Site Ops · Field note

OIDC Discovery URL and Metadata Explained

Understand what the OIDC discovery document is, which metadata fields matter first, and how to debug auth setup when issuer, jwks_uri, or authorization endpoints do not line up.

Encrypt Online Editorial Team3 min read
OIDC Discovery URL and Metadata Explained guide cover

Before you start

Inspect the current certificate, key, token, or endpoint output before changing deployment config; stale artifacts make fixes misleading.

When OIDC discovery fails, start with the /.well-known/openid-configuration document, the exact issuer, and the advertised jwks_uri.

The discovery document tells your client where to send authorization and token requests, where to find public keys, and which capabilities the provider advertises.

Tip: Paste the document itself into a local inspector. The document may contain environment-specific endpoints, and the tool does not need to fetch the provider URL.

What the discovery URL usually looks like

Most providers expose a JSON document at a path like this:

Text
https://id.example.com/.well-known/openid-configuration

A compact example that includes the core required OIDC fields looks like this:

JSON
{
  "issuer": "https://id.example.com",
  "authorization_endpoint": "https://id.example.com/oauth2/authorize",
  "token_endpoint": "https://id.example.com/oauth2/token",
  "jwks_uri": "https://id.example.com/.well-known/jwks.json",
  "userinfo_endpoint": "https://id.example.com/oauth2/userinfo",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

When login breaks, the fastest question is not "is discovery supported?" It is "does my client expect these exact URLs and this exact issuer?"

The three fields that break integrations most often

issuer

The issuer value has to match what tokens later claim in iss. If discovery says https://id.example.com but the token says https://login.example.com, your verifier may reject the token even if the key is correct.

jwks_uri

This is where your verifier finds public keys. If it points to the wrong environment, stale keys or kid mismatches show up later during JWT verification.

authorization and token endpoints

These fields determine where the browser gets redirected and where the app exchanges the authorization code. A copied tenant URL or missing path segment here creates "login works in staging but not production" incidents very quickly.

A practical debugging workflow

  1. Open the discovery document for the exact environment you are using, then paste its JSON into the OIDC Discovery Inspector.
  2. Compare issuer, authorization_endpoint, token_endpoint, and jwks_uri exactly with your application config.
  3. Decode a real token and confirm its iss, aud, alg, and kid.
  4. Paste the JWKS JSON into the JWK / JWKS Inspector if the key-selection step still looks wrong.

That order keeps you from guessing at signatures when the metadata itself already disagrees.

Failure cases that look unrelated at first

  • The app points to the tenant root, but the provider expects a custom authorization-server path.
  • The discovery document is for production while the client ID or redirect URI belongs to staging.
  • The issuer changed during a provider migration, but the verifier still hard-codes the old value.
  • jwks_uri is reachable, but it publishes a different key set than the tokens you are receiving.

Where the local tools help

  • Use OIDC Discovery Inspector to separate required metadata, advertised capabilities, defaults, extensions, and optional exact expectations without fetching the provider.
  • Use JWT Decode to inspect the iss, aud, alg, and kid from a real token.
  • Use JWKS Inspector after you paste the actual JWKS JSON from jwks_uri and want to confirm key selection before debugging library code.

Questions readers usually ask

Is the discovery URL the same as the issuer?

Not exactly. The discovery URL usually hangs off the issuer, but the issuer is the identity value that tokens and clients compare directly.

Do I need discovery if I already know the endpoints?

Not always, but discovery reduces manual drift. The value is strongest when you want one authoritative source for issuer metadata and JWKS location.

Why does the login flow fail even though the discovery document loads?

Because loading the document is only step one. The client still has to use the right issuer, redirect URI, scopes, and endpoints for that environment.

References

Report a correction