OpenID Connect

OpenID Well-Known URL

Introduction

The OpenID Well-Known URL, also known as the OpenID Connect Discovery, is a crucial feature in the OpenID Connect protocol.

It provides a standardized way for clients (applications) to discover essential configuration details about an Identity Provider (IdP).

This discovery process is essential for setting up secure authentication and authorization flows between the client and the IdP.

Purpose of the Well-Known URL

The primary purpose of the OpenID Well-Known URL is to allow clients to retrieve configuration information about the IdP dynamically. This dynamic configuration retrieval has several advantages

1. Simplified Integration: Clients can integrate with multiple IdPs without hardcoding configuration details for each one. This flexibility makes it easier to switch between IdPs or support various authentication providers seamlessly.

2. Security: By obtaining configuration details directly from the IdP, clients reduce the risk of misconfiguration and security vulnerabilities. They can trust that the information received is up-to-date and accurate.

3. Standardization: OpenID Connect Discovery defines a standardized set of configuration parameters, ensuring consistent implementations across different IdPs and clients.

Accessing the Well-Known URL

The OpenID Well-Known URL is constructed by replacing the Issuer URL with the following example. The Issuer URL will be the base URL of the IdP's authorization server.

https://[Issuer-URL]/.well-known/openid-configuration

To retrieve the configuration, a client can perform an HTTP GET request to this URL and receive a JSON response containing critical information about the IdP.

Configuration Details

The JSON response from the Well-Known URL typically includes the following key configuration details:

• issuer: The base URL of the IdP, used for identifying the IdP.

• authorization_endpoint: The URL where the authentication and authorization process begins.

• token_endpoint: The URL for obtaining access tokens and ID tokens.

• userinfo_endpoint: An optional endpoint for retrieving additional user information.

• jwks_uri: The URL where the IdP publishes its JSON Web Key Set (JWKS), used for token validation.

• registration_endpoint: URL for dynamic client registration with the IdP.

• check_session_iframe: URL for checking the session status of a user.

• end_session_endpoint: URL for initiating single sign-out (logout).

• social_token_exchange_url: URL for exchanging tokens with social identity providers.

• device_authorization_endpoint: Endpoint for device-based authentication.

• scopes_supported: Supported scopes that can be requested when obtaining tokens.

• response_types_supported: Supported OAuth 2.0 response types.

• response_modes_supported: Supported response modes for authorization responses.

• grant_types_supported: Supported OAuth 2.0 grant types.

• acr_values_supported: Supported authentication context class references (ACR) values.

• subject_types_supported: Supported subject (user identifier) types.

• id_token_signing_alg_values_supported: Supported algorithms for signing ID tokens.

• id_token_encryption_alg_values_supported: Supported algorithms for encrypting ID tokens.

• id_token_encryption_enc_values_supported: Supported encryption encodings for ID tokens.

• userinfo_signing_alg_values_supported: Supported algorithms for signing user information.

• userinfo_encryption_alg_values_supported: Supported algorithms for encrypting user information.

• userinfo_encryption_enc_values_supported: Supported encryption encodings for user information.

• request_object_signing_alg_values_supported: Supported algorithms for signing request objects.

• request_object_encryption_alg_values_supported: Supported algorithms for encrypting request objects.

• request_object_encryption_enc_values_supported: Supported encryption encodings for request objects.

• token_endpoint_auth_methods_supported: Supported authentication methods at the token endpoint.

• token_endpoint_auth_signing_alg_values_supported: Supported algorithms for signing tokens at the token endpoint.

• display_values_supported: Supported display parameter values.

• claim_types_supported: Supported claim types.

• claims_supported: Supported claims (user attributes).

• claims_locales_supported: Supported language tags for claims.

• ui_locales_supported: Supported language tags for the user interface.

• claims_parameter_supported: Indicates whether the claims request parameter is supported.

• request_parameter_supported: Indicates whether the request request parameter is supported.

• request_uri_parameter_supported: Indicates whether the request_uri request parameter is supported.

• require_request_uri_registration: Indicates whether clients must register request_uri values for request objects.

• service_documentation: URL pointing to documentation for the IdP's services.

• op_policy_uri: URL for the IdP's policy document.

• op_tos_uri: URL for the IdP's terms of service.

• code_challenge_methods_supported: Supported PKCE(Proof Key for Code Exchange) code challenge methods.

Conclusion

The OpenID Well-Known URL is a fundamental feature of the OpenID Connect protocol, enabling secure, flexible, and standardized integration between clients and Identity Providers.

By dynamically discovering configuration details, clients can streamline the authentication and authorization process while enhancing security and interoperability.