Encrypt Online

OIDC Discovery URL and Metadata Explained Without the Hand-Waving

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 Team4 min readCertificates & Site Ops
OIDC Discovery URL and Metadata Explained Without the Hand-Waving guide cover

Tip

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

OIDC discovery feels magical until it breaks. Then you are staring at a /.well-known/openid-configuration URL, a bad issuer value, or a missing jwks_uri and wondering which field actually matters first.

The discovery document is just metadata. It tells your client where the issuer publishes keys, authorization endpoints, token endpoints, and supported capabilities.

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

The document often contains fields like these:

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"
}

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.
  2. Compare issuer, authorization_endpoint, token_endpoint, and jwks_uri with your application config.
  3. Decode a real token and confirm its iss, aud, alg, and kid.
  4. Paste the JWKS JSON into 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 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.

Developer workflow

Use this guide as an operations checklist before changing certificates, tokens, DNS, or deployment settings.

  1. Inspect the current artifact or endpoint output before making changes.
  2. Change one variable at a time so a failed verification has a narrow cause.
  3. Keep the rollback value, expiry, and verification command in the same runbook entry.
Text
1. current deployed artifact
2. single config or key change
3. verify endpoint/client behavior
4. record rollback and expiry details

References

Report a correction