OAuth 2.0 Discovery: RFC 8414 vs. OpenID Connect Discovery 1.0

OAuth 2.0 Discovery Endpoints: RFC 8414 vs. OpenID Connect Discovery 1.0

When a backend service needs to interact with an Identity Provider (IdP), it cannot hardcode endpoint URLs like /token or /authorize. Instead, it relies on a standardized discovery mechanism to resolve capabilities from a known Issuer URL. For backend developers, distinguishing between the two primary discovery standards is critical: /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/openid-configuration (OpenID Connect Discovery 1.0).

This article, Part 5 of the Authorization Server Metadata series, explains why these endpoints are not interchangeable. While they share a common foundation, OIDC adds strict identity-specific schemas that OAuth 2.0 does not mandate. Confusing them leads to implementation errors regarding parameter support and security assumptions.

The Mechanism of Discovery

The discovery process begins when a client receives a known Issuer URI (e.g., https://auth.example.com). The client then performs an HTTP GET request to a well-known path to fetch a JSON document describing the server’s capabilities.

Historically, two standards have emerged for this role. The first is RFC 8414, which defines /.well-known/oauth-authorization-server. This is a separate metadata specification distinct from the core OAuth 2.0 protocol (RFC 6749); many OAuth 2.0 servers do not implement it. The second is OpenID Connect Discovery 1.0, which defines /.well-known/openid-configuration. This is specific to OpenID Connect (OIDC), an identity layer built on top of OAuth 2.0.

Both endpoints respond to an HTTP GET request and return a JSON object. However, the schema of that object differs significantly. Understanding this divergence is essential because OIDC introduces identity-specific claims and endpoints that pure OAuth 2.0 does not require.

Schema Divergence: What Each Document Contains

The well-known oauth-authorization-server endpoint (RFC 8414) and /.well-known/openid-configuration (OpenID Connect Discovery 1.0) share a common subset of fields because OIDC reuses core OAuth 2.0 flows. Both documents typically include:

• issuer: The identifier for the authorization server.
• authorization_endpoint: The URL where the user is redirected for consent.
• token_endpoint: The URL where the client exchanges an authorization code for an access token.
• jwks_uri: The location of the JSON Web Key Set (JWKS) for verifying JWT signatures.

However, OpenID Connect Discovery 1.0 (OIDC) introduces fields that are essential for identity verification but absent in pure OAuth 2.0:

• userinfo_endpoint: A URL that returns claims about the authenticated user.
• scopes_supported: A list of supported scopes, often including openid by default.
• claims_supported: A list of claims (e.g., name, email) that can be requested.
• response_types_supported: Specifically includes id_token and id_token token responses, which are core to OIDC’s implicit and hybrid flows.

Conversely, RFC 8414 (OAuth 2.0) may include fields irrelevant to OIDC, such as revocation_endpoint or introspection_endpoint, if the server supports OAuth 2.0 token management but not identity assertions.

The key takeaway is that OIDC is a profile of OAuth 2.0. An OIDC-compliant server must support OAuth 2.0, but an OAuth 2.0 server is not required to support OIDC. Therefore, an OIDC discovery document is a superset of the OAuth 2.0 metadata document in terms of identity capabilities.

Operational Implications for Backend Developers

Backend developers often assume that if a server supports OAuth 2.0, it also supports OIDC. This is a dangerous assumption. Many legacy systems or specialized providers do not implement discovery at all, forcing developers to hardcode URLs. Others may support OAuth 2.0 for API access but provide no user identity information, lacking the openid-configuration document entirely.

Fallback Strategy

A robust client implementation should attempt to discover both endpoints. The order of operations matters:

1. Try /.well-known/openid-configuration first. If this succeeds, the server is OIDC-compliant. Use this document for all identity-related operations (user info, ID token validation).
2. Fall back to /.well-known/oauth-authorization-server. If the OIDC endpoint fails (404 or invalid JSON), try the OAuth 2.0 endpoint. Use this only for authorization and token exchange. Do not attempt to call userinfo_endpoint or validate ID tokens, as they likely do not exist.
3. Handle missing discovery gracefully. If neither endpoint is available, the provider relies on hardcoded URLs. In this case, you must manually configure the token_endpoint, authorization_endpoint, and jwks_uri based on provider documentation.

Security Risk: Trust Boundary

If you treat an OAuth 2.0 endpoint as an OIDC provider, you may expose your application to security risks. For example, if you expect an id_token in the response but the server only supports OAuth 2.0, you might receive a plain access token. If your code blindly validates the access token as an ID token using the JWKS from the OAuth document, you might bypass critical identity checks. Always verify the presence of OIDC-specific fields before processing identity claims.

Worked Scenario: Auth0 vs. Legacy Payment Gateway

Consider two backend integrations to illustrate the practical differences.

Case 1: Auth0 (OIDC-Compliant)

Auth0 is an OIDC provider. Its /.well-known/openid-configuration returns:

{
  "issuer": "https://dev-xxxx.auth0.com/",
  "authorization_endpoint": "https://dev-xxxx.auth0.com/authorize",
  "token_endpoint": "https://dev-xxxx.auth0.com/oauth/token",
  "userinfo_endpoint": "https://dev-xxxx.auth0.com/userinfo",
  "jwks_uri": "https://dev-xxxx.auth0.com/.well-known/jwks.json",
  "response_types_supported": ["code", "token", "id_token", "code token", "code id_token", "token id_token", "code id_token token"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

Here, the backend can safely call /userinfo and expect an id_token.

Case 2: Legacy Payment Gateway (No Discovery)

Many legacy payment gateways use OAuth 2.0 for merchant access but do not publish any discovery documents. They require the developer to hardcode all endpoint URLs. There is no /.well-known/openid-configuration or /.well-known/oauth-authorization-server file available.

In this scenario, your backend must rely on static configuration:

{
  "issuer": "https://api.legacy-gateway.com",
  "authorization_endpoint": "https://api.legacy-gateway.com/oauth/authorize",
  "token_endpoint": "https://api.legacy-gateway.com/oauth/token",
  "jwks_uri": "https://api.legacy-gateway.com/.well-known/jwks.json"
}

Notice the absence of userinfo_endpoint, scopes_supported (with openid), and id_token response types. If your backend tries to fetch user info from this gateway using an OIDC client, it will fail. You must use the OAuth 2.0 flow to get an access token and then call the gateway’s REST API directly to retrieve merchant data, as identity claims are not returned via standard OIDC mechanisms.

Conclusion

The distinction between oauth-authorization-server and openid-configuration is not semantic; it is architectural. RFC 8414 defines the plumbing for authorization. OpenID Connect Discovery 1.0 defines the plumbing for identity. Backend developers must check for the existence of OIDC-specific fields before assuming identity capabilities. Failure to do so results in broken integrations or security vulnerabilities. Always treat the discovery document as the source of truth, never as a hint, and remember that many providers may not support the well-known oauth-authorization-server or openid-configuration endpoints at all, requiring manual configuration.