It is a JSON document, served at the issuer URL plus /.well-known/openid-configuration, that tells an app where an OpenID provider's endpoints and signing keys are. Apps fetch it instead of hard coding URLs. Validate that its issuer value matches the URL you fetched it from.
Where it lives
The OpenID Connect Discovery spec says providers that support discovery must make a JSON document available at the path formed by adding /.well-known/openid-configuration to the issuer. It must be returned with the application/json content type. The spec says it should support CORS so browser based clients can read it.
For example, an issuer of https://id.example.com serves its metadata at https://id.example.com/.well-known/openid-configuration.
What is inside
| Field | Status in the spec | What it is |
|---|---|---|
| issuer | Required | The provider's identifier, an https URL |
| authorization_endpoint | Required | Where the user is sent to sign in |
| token_endpoint | Required unless only implicit flow is used | Where the app swaps a code for tokens |
| jwks_uri | Required | The location of the signing keys |
| userinfo_endpoint | Recommended | Where to fetch profile claims |
| end_session_endpoint | Defined by the RP-initiated logout spec | Where to send users to log out |
Real documents contain many more fields, such as supported scopes, signing algorithms and PKCE methods. The table above shows only the ones named in the specs this post cites.
What to validate
The spec is firm about one point. The issuer value in the document must be identical to the issuer URL used as the prefix to fetch it, and also identical to the iss claim in ID tokens from that provider. If any validation fails, the information must not be used.
In practice, that means:
- Fetch the document over https only.
- Compare
issuerto the URL you configured. Reject a mismatch. - Compare the
issclaim of every ID token to the same value. - Take signing keys only from the
jwks_uriin the validated document. - Do not follow a discovery URL supplied by an end user or by data you do not control without allow listing.
Why this matters for security
If an attacker can steer your app to a discovery document they control, they can point it at their own keys and mint tokens your app accepts. Fixed, configured issuers, strict equality checks, and https prevent that. This is also the foundation of defences against mix up attacks, where a client confuses which provider answered.
Caching and failure
Cache the document with a sensible lifetime and refresh on a schedule. If a fetch fails at startup, fail closed or use the last known good copy, depending on your risk. Do not fall back to values from the token itself.
Quick check
Is discovery mandatory for OpenID providers?
No. The spec treats issuer discovery as optional, and a relying party that already knows the provider's configuration can skip it. Providers that support discovery must serve the document.
Can I trust any URL ending in openid-configuration?
No. Trust only documents fetched from an issuer you configured, and check that the issuer value matches.
Safeguard's SBOM and dependency scanning can help you track which identity libraries your applications depend on. See what turns up with a free scan.
Sources
Last reviewed: 19 October 2026.
