Discovery Endpoints

Overview

The Discovery Endpoint (also called the OpenID Provider Configuration Document) is defined in the OpenID Connect Discovery specification.

It provides a JSON document at a well-known location that describes the Identity Provider’s (IdP’s) capabilities and endpoints. Clients (RPs) can use this to automatically configure themselves instead of requiring manual configuration of URLs and supported features.

Endpoint

GET https://[BASE_URL]/.well-known/openid-configuration

Response

The response is a JSON object containing metadata about the IdP. Example:

{
   "issuer": "https://[BASE_URL]",
   "authorization_endpoint": "https://[BASE_URL]/connect/authorize",
   "token_endpoint": "https://[BASE_URL]/connect/token",
   "userinfo_endpoint": "https://[BASE_URL]/connect/userinfo",
   "end_session_endpoint": "https://[BASE_URL]/connect/endsession",
   "jwks_uri": "https://[BASE_URL]/.well-known/openid-configuration/jwks",
   "check_session_iframe": "https://[BASE_URL]/connect/checksession",
   "introspection_endpoint": "https://[BASE_URL]/connect/introspect",
   "revocation_endpoint": "https://[BASE_URL]/connect/revocation",
   "scopes_supported": ["openid", "profile", "email"],
   "response_types_supported": ["code", "id_token", "token id_token"],
   "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
   "subject_types_supported": ["public", "pairwise"],
   "id_token_signing_alg_values_supported": ["RS256"],
   "claims_supported": ["sub", "name", "email", "email_verified"]
}

Usage

  1. Client retrieves configuration at startup:

    HTTP GET https://[BASE_URL]/.well-known/openid-configuration

  2. Client dynamically discovers the necessary endpoints and metadata:

  • Authorization Endpoint
  • Token Endpoint
  • UserInfo Endpoint
  • End Session Endpoint
  • Check Session IFrame
  • Supported scopes, response types, and signing algorithms
  1. Client uses the JWKS URI (jwks_uri) to fetch public keys for verifying ID Tokens.

Security Considerations

  • Validate that the issuer field matches the expected IdP issuer.
  • Cache discovery results for efficiency, but refresh periodically to catch configuration changes.