WSS
Web Specification Studio Home
On this page
Well-Known URIsOptionalUpdated

/.well-known/openid-configuration

A JSON discovery document that describes an OpenID Connect provider's endpoints and capabilities. Only required if you are an OIDC identity provider.

What it is

/.well-known/openid-configuration is a JSON document published by an OpenID Connect (OIDC) provider that describes how clients can interact with it. A relying party fetches this URL, parses the response, and then knows where to send authorisation requests, where to exchange tokens, how to verify signatures, and which features the provider supports.

The format is defined by OpenID Connect Discovery 1.0. A closely related document for plain OAuth 2.0 lives at /.well-known/oauth-authorization-server (RFC 8414).

Why it matters

  • Zero hand-configuration. A client only needs your issuer URL. It discovers everything else from this document.
  • Key rotation works. The jwks_uri is the canonical source for signing keys. Rotate keys there and every client picks up the change.
  • Capability negotiation. Clients see which scopes, claims, response types and signing algorithms you support, and behave accordingly.
  • Standardisation. Every major identity library (Auth0, Okta, Keycloak, Microsoft Entra, Google, etc.) consumes this format. You do not have to write client SDKs.

Only publish this if you actually run an OIDC identity provider. A site that uses “Sign in with Google” is a relying party, not a provider, and should not expose this URL.

How to implement

Serve the file as application/json from your issuer’s origin. The minimum useful payload looks roughly like this:

{
  "issuer": "https://login.example.com",
  "authorization_endpoint": "https://login.example.com/oauth2/authorize",
  "token_endpoint": "https://login.example.com/oauth2/token",
  "userinfo_endpoint": "https://login.example.com/oauth2/userinfo",
  "jwks_uri": "https://login.example.com/oauth2/jwks",
  "response_types_supported": ["code", "id_token", "code id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"]
}

Rules:

  • The issuer value must exactly match the URL clients use, including scheme and absence of trailing slash. Mismatches are the single most common cause of “invalid issuer” errors.
  • Always serve over HTTPS.
  • Set Cache-Control sensibly - minutes to hours, not days. Clients re-fetch on errors.
  • The jwks_uri must be reachable and return current signing keys.

Common mistakes

  • Publishing the file but having clients fail with “issuer mismatch” because the URL differs by a trailing slash, port number, or hostname casing.
  • Exposing a stale jwks_uri after rotating keys.
  • Marking the file as text/html because a framework rendered it as a page.
  • Treating the file as static when endpoints actually move. If you change endpoints, change the file.

OpenID Connect Discovery 1.0 Specification

Exposing OpenID Connect identity provider configuration for automated client discovery requires adhering to OpenID Foundation standards:

  • Mandatory Endpoint Declaration: Serve /.well-known/openid-configuration with Content-Type: application/json over HTTPS. The JSON payload MUST contain issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and supported algorithms (id_token_signing_alg_values_supported).
  • Exact Issuer Identifier Match: The issuer property value MUST exactly match the URI used to access the document, with no trailing slashes (https://auth.example.com). Mismatches cause OIDC SDKs (OIDC Client, NextAuth) to reject token signatures.
  • Dynamic JWKS Key Rotation Linkage: Set jwks_uri to point to the live JSON Web Key Set endpoint. Relying parties cache JWKS keys and fetch updates dynamically upon encountering unknown key IDs (kid header claims).

Verification

curl -s https://login.example.com/.well-known/openid-configuration | jq .

The response should be valid JSON with at least issuer, authorization_endpoint, token_endpoint and jwks_uri. The issuer value must equal the URL prefix you advertise to clients.

Related topics

Sources & further reading

Add as a preferred source on Google