Category: OAuth & OIDC

OpenID Connect Discovery

Also known as: OIDC Discovery, OpenID Connect Discovery 1.0, OIDC Discovery

Simply put

OpenID Connect Discovery is a mechanism that lets an application find out where a user's identity provider is and how to communicate with it, without that information being configured by hand in advance. Instead of manually entering connection details, the application can retrieve them automatically from a standard location published by the identity provider. This makes it easier to set up sign-in flows across different providers.

Formal definition

OpenID Connect Discovery 1.0 (OpenID Foundation specification, most recently published as errata set 2 in December 2023) defines a mechanism by which an OpenID Connect Relying Party can discover the End-User's OpenID Provider and obtain the metadata needed to interact with it. OpenID Connect itself is an identity (authentication) layer built on top of the OAuth 2.0 authorization framework, enabling clients to verify the identity of the End-User; Discovery supports this by providing the provider configuration needed before authentication flows begin. In typical deployments, provider metadata is published at a well-known endpoint (commonly referenced as the .well-known endpoint), from which clients dynamically retrieve OpenID Provider information such as endpoint locations and supported capabilities. Note that Discovery addresses locating and describing the provider; the actual authentication of the End-User, token issuance, and token validation are handled by other parts of the OpenID Connect and OAuth 2.0 specifications and are out of scope for the Discovery specification itself. Exact metadata fields and behavior depend on the provider's configuration and conformance to the specification.

Why it matters

OpenID Connect Discovery reduces the manual configuration burden of integrating with identity providers. Without it, a Relying Party developer must obtain and hand-enter connection details such as endpoint locations and supported capabilities for each OpenID Provider. This manual approach is error-prone and brittle: when a provider rotates signing keys or changes an endpoint, statically configured clients can break unless they are updated in step. Discovery allows a client to retrieve current provider metadata from a standard, well-known location instead, which simplifies onboarding across multiple providers and helps clients stay aligned with provider configuration changes over time.

For organizations operating at scale, Discovery is a practical enabler of federation flexibility. Because provider metadata is published in a predictable, standardized structure, it becomes feasible to support many identity providers, or to switch providers, with less bespoke integration code. It also supports interoperability efforts: ecosystem programs, such as those in open banking, reference the OIDC Discovery well-known endpoint as the defined place to describe a provider's configuration, which gives participants a common contract to build against.

It is important to scope expectations correctly. Discovery is concerned with locating and describing the provider, not with authenticating the end user or issuing and validating tokens, those responsibilities belong to other parts of the OpenID Connect and OAuth 2.0 specifications. Treating Discovery as a security boundary in itself would be a mistake; the metadata it returns is only as trustworthy as the transport and the provider publishing it, and the actual assurance of a sign-in comes from the authentication flow and token validation that follow. Because exact metadata fields and behavior depend on the provider's configuration and conformance, integrators should not assume that every capability advertised or expected is uniformly implemented across providers.

Who it's relevant to

IAM Engineers and Integration Developers

Engineers building sign-in flows use Discovery to retrieve provider metadata automatically rather than hand-configuring endpoint locations and supported capabilities for each OpenID Provider. This reduces integration effort when onboarding new providers or supporting several at once, though implementers should account for variation in what each provider advertises and how closely it conforms to the specification.

Security Architects

Architects designing federation topologies benefit from Discovery's standardized, well-known metadata endpoint as a common contract across providers. They should also scope its role correctly: Discovery locates and describes the provider, while authentication of the end user and token validation are handled by other parts of the OpenID Connect and OAuth 2.0 specifications and remain where the actual security assurances live.

Ecosystem and Interoperability Program Participants

Participants in federated ecosystems, such as open banking programs that reference the OIDC Discovery well-known endpoint as the defined place to publish provider configuration, rely on Discovery to give all parties a consistent, predictable structure to build and test against.

System Administrators Operating Identity Providers

Administrators responsible for an OpenID Provider are the ones publishing the metadata that Relying Parties consume. Because clients may retrieve this configuration dynamically, keeping the published endpoint accurate and current, for example when endpoints change, helps dependent clients continue to function without manual reconfiguration on their side.

Inside OIDC Discovery

Discovery document (OpenID Provider Metadata)

A JSON document, typically served at the /.well-known/openid-configuration path relative to the issuer, that advertises an OpenID Provider's configuration so relying parties can consume it programmatically rather than being manually configured.

issuer

The identifier value that names the OpenID Provider. In most deployments it must exactly match the iss claim in issued ID tokens and forms the base against which the well-known metadata path is constructed.

Endpoint URLs

Metadata fields such as authorization_endpoint, token_endpoint, userinfo_endpoint, and end_session_endpoint (where supported) that tell the relying party where to direct the respective OIDC and underlying OAuth 2.0 requests.

jwks_uri

A URL pointing to the provider's JSON Web Key Set, which publishes the public keys a relying party uses to verify the signatures on JWTs such as ID tokens. Signature verification is distinct from encryption; publishing keys here supports validation, not confidentiality.

Capability metadata

Fields advertising supported behaviors, such as scopes_supported, response_types_supported, grant_types_supported, subject_types_supported, id_token_signing_alg_values_supported, and token_endpoint_auth_methods_supported, which describe what the provider can do rather than what any given client is entitled to.

WebFinger-based issuer discovery

A separate, optional mechanism defined for locating a user's OpenID Provider from a user-supplied identifier before the metadata document itself is retrieved. This is distinct from fetching the provider metadata and is not always deployed.

Common questions

Answers to the questions practitioners most commonly ask about OIDC Discovery.

Does OpenID Connect Discovery itself authenticate users?

No. Discovery is a metadata-retrieval mechanism, not an authentication step. It allows a client (relying party) to programmatically obtain an OpenID Provider's configuration, such as endpoint URLs, supported scopes, and signing key locations, typically from a well-known configuration document. Authentication of the end user happens later, during the actual OpenID Connect authentication flow that Discovery helps the client configure. Keep the steps separate: Discovery is about locating and describing the provider, while authentication verifies the user's identity.

Is OpenID Connect Discovery the same thing as dynamic client registration?

No, though the two are often used together and are sometimes confused. Discovery lets a client learn about the OpenID Provider's capabilities and endpoints. Dynamic client registration is a separate mechanism by which a client registers itself with the provider to obtain client credentials and metadata. A deployment can use one without the other: you might use Discovery to configure a statically registered client, or register dynamically against a provider whose endpoints you already know. They address different concerns.

How does a client typically locate an OpenID Provider's Discovery metadata?

In most deployments the client requests a well-known configuration document derived from the provider's issuer identifier, commonly at a path under /.well-known/. The returned JSON document typically lists endpoints (authorization, token, userinfo), the jwks_uri for signing keys, supported scopes, response types, and signing algorithms. The exact contents and which fields are present depend on the provider and its configuration, so clients should validate that required fields exist rather than assuming a fixed shape.

What should a client validate when consuming a Discovery document?

At minimum, confirm that the document was retrieved over a secure transport and that the issuer value matches the expected issuer identifier, since the issuer is later used to validate ID token claims. Clients typically also check that the endpoints they intend to use are present and that the advertised signing algorithms are ones the client supports. Depending on your security posture, you may cache the metadata and the keys referenced by jwks_uri, while planning for key rotation.

How does Discovery relate to retrieving the provider's signing keys?

The Discovery document typically includes a jwks_uri pointing to the provider's JSON Web Key Set, which contains the public keys used to verify the signatures on tokens such as ID tokens. Discovery does not deliver the keys directly; it points the client to where the key set can be fetched. Note that signature verification confirms integrity and origin of a signed token but is distinct from encryption, a signed token is not necessarily an encrypted one.

How often should a client refresh Discovery metadata and keys?

This depends on configuration and vendor guidance rather than a single fixed rule. Because providers may rotate signing keys and change endpoint or capability details over time, clients commonly cache the Discovery document and key set for a bounded period and refresh them, often triggering a refresh of the key set when an unrecognized key identifier is encountered during token validation. Balance freshness against the load and latency of repeated retrieval, and follow any cache-control signals the provider supplies.

Common misconceptions

OpenID Connect Discovery authenticates the user or the provider.

Discovery is a configuration and metadata-retrieval mechanism, not an authentication step. It tells a relying party where and how to interact with the provider; the actual authentication of the end user happens later through the OIDC flow, and verifying the provider's identity depends on transport security and signature validation using keys from jwks_uri.

The discovery document lists the permissions a particular client has.

The metadata advertises the provider's overall capabilities (such as scopes_supported), not per-client authorization. What a specific client may request or receive is governed by client registration and the provider's authorization decisions, which are separate from discovery.

Because the metadata and keys are published at a well-known URL, they are inherently trusted and static.

The document is retrieved over the network and can change; keys published at jwks_uri may rotate. Relying parties should protect retrieval with TLS and refresh cached metadata and keys according to configuration, rather than treating a one-time fetch as permanently authoritative.

Best practices

Retrieve the discovery document and jwks_uri only over TLS, and validate that the issuer value returned matches the expected issuer and the iss claim in received tokens.

Cache the discovery metadata and JWKS, but refresh them on a sensible schedule and handle key rotation gracefully so signature verification does not break when the provider rotates signing keys.

Use the advertised capability fields (such as id_token_signing_alg_values_supported and token_endpoint_auth_methods_supported) to select algorithms and authentication methods you actually support, and reject configurations that would force weaker options where policy allows.

Do not treat a signature-verification key from jwks_uri as providing confidentiality; if you require encrypted tokens, confirm the provider supports and is configured for encryption separately.

Avoid hardcoding endpoint URLs when the provider supports discovery; consume them from the metadata so client configuration stays aligned with provider changes, while confirming the well-known path is derived correctly from the issuer.

Where issuer discovery from a user identifier is needed, treat WebFinger-based lookup as a separate, optional step and confirm the provider supports it rather than assuming it is available.