Well Known OpenID Configuration

Identify what the OIDC lookup needs to find

An OIDC configuration lookup retrieves provider metadata used to configure an OpenID Connect client. It does not search for a person or prove that a token is valid. If you already know the issuer through trusted configuration, discovery can start there. WebFinger is an optional issuer-discovery mechanism. An email domain by itself is not authorization to trust any server it suggests.

The OpenID Connect Discovery specification separates locating the issuer from retrieving its configuration. For mapping an authenticated login to an internal account, use the separate identity linking guide.

Read metadata as configuration, not credentials

This abridged illustrative document uses reserved example hosts. It is not a complete production configuration or a live provider response.

{
  "issuer": "https://id.example.com/realm",
  "authorization_endpoint": "https://id.example.com/realm/authorize",
  "token_endpoint": "https://id.example.com/realm/token",
  "jwks_uri": "https://id.example.com/realm/keys",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

The issuer identifies the provider namespace. Authorization and token endpoints serve different protocol steps. The JWKS URI supplies public keys. Capability arrays inform client compatibility. They do not override the application's allowed algorithms or chosen flow. An optional UserInfo or logout endpoint is another protocol surface, not evidence that a user session exists.

Construct the URL from the intended issuer

For OIDC discovery, remove a terminating slash from the issuer for the configuration-request construction, then append /.well-known/openid-configuration. Preserve the issuer's path. An issuer such as https://id.example.com/realm therefore has a metadata request at https://id.example.com/realm/.well-known/openid-configuration. Validation still compares the returned issuer against the intended issuer exactly. Do not silently rewrite the configured identity namespace.

OAuth authorization-server metadata under RFC 8414 uses a different well-known suffix and path construction. Do not swap those rules for a path-bearing issuer merely because a provider exposes both documents. Follow the protocol and SDK contract you are actually configuring.

Bound the network trust before fetching metadata

As an application design rule, allow only intended issuers and constrain outbound requests, redirects, resolved addresses, response size and time. A user-entered discovery URL can otherwise become a server-side request surface. Review metadata and JWKS fetches under the same trust policy. HTTPS alone does not establish that a host is an approved identity provider.

Reject issuer mismatch and TLS validation failures instead of disabling verification to make discovery succeed. Use a client implementation that applies the specification's issuer and endpoint checks. Private test deployments need an explicitly controlled trust setup. A custom CA setting is not a reason to accept arbitrary certificates in production.

Handle metadata and keys as separate cached resources

Keep the trusted issuer, metadata and key-cache state distinguishable. Define bounded refresh behavior and failure handling so an unavailable endpoint or an unknown key identifier cannot trigger an uncontrolled fetch loop. Test a legitimate key rotation and a document that changes an endpoint unexpectedly.

Finding a key with a matching kid is only key selection. Token acceptance still needs the applicable signature, issuer, audience, time and flow checks. A JWKS download is not token introspection or an authentication result. Record cache age and refresh outcomes without logging credentials or full tokens.

Diagnose the failing boundary

Keep the failure stage visible in diagnostics. Invalid JSON, unreachable metadata and a rejected token are different events with different repair paths.

Download the evaluation worksheet and record the owner, evidence and decision for each row. Its review fields are blank; it is a reusable template, not a completed assessment.

Separate provider metadata, user claims and token state

Discovery describes the provider. UserInfo returns claims about an authorized end-user request. Token introspection, when supported under its applicable protocol, reports token state to an authorized caller. None is a public directory of people.

OpenID Connect Core requires UserInfo's subject to match the ID token's subject before its claims are used. Account linking additionally needs authorization for the mapping change. Reading an email from UserInfo does not supply that authorization. A configuration viewer should inspect public metadata without asking the user to paste a client secret or access token.

Use provider documentation for the exact namespace

Google's public discovery document reports https://accounts.google.com as its issuer. Microsoft Entra documentation explains tenant-scoped authorities and audience-dependent choices; common is not a substitute for deciding the application's accepted audience.

Keycloak documents the realm-specific path /realms/{realm-name}/.well-known/openid-configuration. Auth0 documents discovery under the configured tenant domain. For Okta, Cognito and other providers, identify the intended authorization server or user-pool issuer in their current documentation. Do not infer the correct namespace from another tenant's example or from a generic online lookup result.

Sources

Documentation checked November 14, 2026.

1. OpenID Connect Discovery 1.0
2. OpenID Connect Core
3. OAuth Authorization Server Metadata