OpenID Discovery Generator

/.well-known/openid-configuration: the discovery document that wires up OIDC

OpenID Connect (OIDC) is the authentication layer that sits on top of OAuth 2.0 (RFC 6749). OAuth solves "this app is allowed to call this API on a user's behalf"; OIDC adds "and here is verified information about who that user is" via a signed ID Token. The discovery document published at the well-known path /.well-known/openid-configuration is the JSON metadata file that every OIDC client fetches once at startup to learn where the provider's endpoints live — issuer, authorization, token, userinfo, JWKS, end-session, the whole map. Defined by the OpenID Connect Discovery 1.0 spec, it is what turns OIDC into a plug-and-play protocol: paste an issuer URL into Auth0, Keycloak, MSAL or oidc-client-ts and the library fetches everything else automatically.

The minimum useful document declares the issuer plus a handful of endpoint URLs and crypto preferences. A working response looks like this:

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

Required vs optional fields

The fields above are required by the discovery spec. Optional but ubiquitous: scopes_supported (advertises openid, profile, email, offline_access), claims_supported (a hint at which userinfo fields the IdP can return), end_session_endpoint (for RP-initiated logout), revocation_endpoint and introspection_endpoint (RFC 7009 and RFC 7662 — both adopted from OAuth into OIDC ecosystems), code_challenge_methods_supported (S256 for PKCE — required for any modern SPA or mobile client), token_endpoint_auth_methods_supported, and grant_types_supported.

Identity providers and self-hosting options

Major commercial IdPs publishing OIDC discovery: Google (accounts.google.com/.well-known/openid-configuration), Microsoft Entra ID (formerly Azure AD), Apple Sign In, Auth0, Okta, AWS Cognito, Firebase Auth, Stytch and Clerk. Self-hosted options that are battle-tested: Keycloak (Red Hat, Java), Authentik (Python, the modern choice for self-hosters), ZITADEL (Go, multi-tenant), Ory Kratos + Hydra (Go, cloud-native split), Dex (Go, gateway in front of LDAP/SAML), Casdoor and FusionAuth. All of them ship a discovery endpoint out of the box; the generator on this page is for crafting one manually when implementing a custom IdP or mocking one in tests.

Flows, JWKS and PKCE

The Authorization Code Flow with PKCE (Proof Key for Code Exchange) is the current best-practice flow for SPAs, mobile apps and server-side web apps alike — the legacy Implicit Flow is deprecated. The jwks_uri publishes the public keys (in JWK format) that clients use to verify the signature on the ID Token, which is a signed JWT containing claims like sub, email, name, picture and aud. The well-known endpoint is typically CORS-enabled (Access-Control-Allow-Origin: *) and cached for an hour or so — clients refetch periodically to pick up key rotation. RFC 8414 defines a parallel mechanism, /.well-known/oauth-authorization-server, for pure-OAuth servers that don't speak OIDC.

Frequently asked questions

Do I need this for plain OAuth 2.0? No — the document is OIDC-specific. Pure OAuth 2.0 servers can publish /.well-known/oauth-authorization-server instead (RFC 8414), and many do both.

Can I self-host an OIDC provider? Yes — Keycloak, Authentik, ZITADEL and Ory Hydra are all production-grade open source. Each generates the discovery document for you and exposes a JWKS endpoint.

Who actually reads this file? OIDC client libraries: oidc-client-ts and oauth4webapi in the browser, MSAL for Microsoft stacks, AppAuth on mobile, panva/node-openid-client on Node, Authlib on Python and Spring Security on Java. They all bootstrap from the issuer URL alone.

Why is the path well-known? RFC 8615 reserves /.well-known/ as a global registry of standard URI suffixes so different protocols don't collide. Same place that hosts security.txt, ACME challenges, MTA-STS and Matrix federation discovery.