The Discovery Document

OpenID Connect offers several methods for obtaining tokens. Many client libraries can automatically select the appropriate method by reading the server’s discovery document. The discovery document is a JSON file served by the OpenID Connect provider, typically available at the /.well-known/openid-configuration endpoint.

The Discovery Document is defined in the official specification: OpenID Connect Discovery 1.0 incorporating errata set 2.

This is what a discovery document may look like:

{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "userinfo_endpoint": "https://example.com/oauth/userinfo",
  "jwks_uri": "https://example.com/oauth/jwks",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code", "token", "id_token"],
  "grant_types_supported": ["authorization_code", "implicit"]
}

Using The Discover Endpoint To Find OAuth Endpoints

Neither the OpenID Connect nor the OAuth specifications define fixed URLs for endpoints like /token or /authorize. However, they do define a standard URL for the discovery document. This document allows clients to dynamically discover the configuration and endpoint locations of an authorization server.

By retrieving the discovery document, clients can determine which endpoints to use. The document includes:

• Authorization endpoint – The URL where users are redirected to authenticate.
• Token endpoint – The URL clients use to exchange credentials or authorization codes for tokens.
• JWKS URI – The location of the provider’s public keys, used to verify token signatures.

The Discovery Document not only reveals the locations of endpoints — it also provides metadata that helps clients understand how to interact with them. This metadata allows the client to determine which authorization flows are supported. These details are defined in the following properties:

• Supported scopes – A list of accepted scopes, such as openid, email, or profile.
• Supported response types – For example, code, id_token, or token.
• Supported grant types – Such as authorization_code, client_credentials, and others.

Spoofing - Always Verify The Discovery Document!

Having a Discovery Document makes an authorization server more usable. However, it comes at a cost: it introduces an attack surface. If an attacker is able to spoof the document, they could relay requests and steal sensitive data (e.g., tokens, user info, etc.). That's why it's important to verify at least three aspects of the discovery document:

• The issuer listed in the discovery document MUST match the URL where it is hosted, exactly.
• The jwks.json document MUST be hosted on the same domain as the discovery document.
• All URIs MUST use HTTPS to ensure secure communication.

The Development Experience

Implementing OAuth can be challenging, often requiring trial and error. Without a clear understanding of the features supported by the authorization server, integrating OAuth into a site or app can feel daunting. This is why utilizing the discovery document during the development process can be incredibly helpful.

Our Opinion

A discovery document is not only useful but also enhances portability. While it does introduce some risks, it remains a critical component of any authorization server. To mitigate these risks, it is essential that the document complies with best practices and that the key endpoints are hosted on the same domain as the issuer. Additionally, it is important to verify the document’s integrity before fully trusting its contents.