Physical Address
304 North Cardinal St.
Dorchester Center, MA 02124
ISO/IEC 26132:2024 OpenID Connect Discovery 1.0 — Finding Identity Providers
How OpenID Connect Relying Parties discover OpenID Providers using WebFinger and configuration metadata
1. The Discovery Protocol Overview
ISO/IEC 26132:2024 defines OpenID Connect Discovery 1.0, a mechanism that enables an OpenID Connect Relying Party (RP) to discover the end-user’s OpenID Provider (OP) and obtain the configuration information needed to interact with it, including OAuth 2.0 endpoint locations.
The discovery process addresses a fundamental question: given an end-user identifier, how does the client application know which identity provider to talk to and what endpoints to use? The standard solves this through a two-step process using WebFinger and a well-known configuration endpoint.
Discovery enables truly decentralized identity scenarios. A single client application can support users from any OpenID Provider without prior per-provider configuration, dramatically reducing onboarding friction.
2. OpenID Provider Issuer Discovery via WebFinger
The issuer discovery process determines the location of the OpenID Provider using the WebFinger protocol (RFC 7033):
| Step | Action | Description |
|---|---|---|
| 1 | User Input | End-user supplies an identifier (email, URL, or other format) to the RP |
| 2 | Normalization | RP normalizes the identifier to determine the Resource and Host |
| 3 | WebFinger Request | RP makes HTTP GET to the Host’s WebFinger endpoint with the resource parameter |
| 4 | Response Parsing | RP extracts the Issuer location from the href value of the link relation http://openid.net/specs/connect/1.0/issuer |
Identifier normalization supports multiple formats:
- Email address syntax:
user@example.com— normalized toacct:user@example.com - URL syntax:
https://example.com/user— used directly as the Resource - Hostname and port:
example.com:8080— used as both Resource and Host - Account URI:
acct:user@example.com— explicit account format
All WebFinger communication MUST use TLS. Additionally, the WebFinger endpoint SHOULD support CORS (Cross-Origin Resource Sharing) to enable browser-based JavaScript clients to perform discovery directly.
3. OpenID Provider Configuration Information
Once the issuer URL is discovered, the RP retrieves configuration metadata from a well-known location. The OP publishes a JSON document at https://{issuer}/.well-known/openid-configuration containing:
| Metadata Field | Type | Description |
|---|---|---|
issuer |
String | OP’s issuer identifier URL (MUST match the discovery URL) |
authorization_endpoint |
String | URL of the OAuth 2.0 Authorization Endpoint |
token_endpoint |
String | URL of the OAuth 2.0 Token Endpoint |
userinfo_endpoint |
String | URL of the OpenID Connect UserInfo Endpoint |
jwks_uri |
String | URL of the OP’s JSON Web Key Set document |
scopes_supported |
Array | JSON array containing supported scope values |
response_types_supported |
Array | JSON array containing supported response type values |
subject_types_supported |
Array | JSON array of subject identifier types (public or pairwise) |
id_token_signing_alg_values_supported |
Array | JSON array of supported JWS signing algorithms for ID Token |
When implementing an RP, cache the provider configuration response with appropriate TTL. The configuration rarely changes, and caching eliminates a round-trip for every authentication request. Use the
cache-control headers from the configuration response to determine the refresh interval.4. Engineering Insights for Discovery Implementation
Key engineering considerations when implementing or using OpenID Connect Discovery:
- Provider Metadata Validation: Always verify that the
issuervalue in the configuration response exactly matches the issuer URL used to fetch it. This prevents a class of phishing attacks where a malicious provider presents a false identity. - CORS Support: The WebFinger endpoint should support CORS to enable browser-based discovery. Without CORS, JavaScript clients cannot perform discovery directly and must rely on backend services.
- Stateless Operation: Discovery is entirely stateless from the RP perspective — no prior registration or configuration with specific providers is needed to discover them.
Impersonation attacks are a primary threat in the discovery flow. An attacker who can control the WebFinger response can redirect the RP to a malicious OpenID Provider. TLS is mandatory for all discovery communication, and RPs MUST validate the issuer identity.
Frequently Asked Questions
Q: Is discovery mandatory for all OpenID Connect implementations?
A: No. Discovery is optional. If an RP already knows the OP’s issuer location through an out-of-band mechanism (e.g., configuration file), it can skip the WebFinger step and proceed directly to provider configuration retrieval.
Q: How does discovery work with email-based identifiers?
A: When a user enters an email address, the RP normalizes it to the acct: URI scheme (e.g., acct:user@example.com), performs a WebFinger lookup on the domain portion, and receives the OpenID Provider issuer URL in the response. This enables any email domain to act as an identity provider.
Q: What happens if the WebFinger endpoint is unavailable?
A: The RP should treat the discovery failure as an authentication error and display an appropriate message to the user. Implementations should also consider fallback mechanisms, such as trying alternative identifier formats or allowing manual provider URL entry.
