The discovery document, also referred to as the "well-known endpoint," contains OpenID Connect values that can be retrieved by OIDC clients. The discovery document enables OIDC clients to configure themselves in order to be able to access your implementation of Next Identity. A client that connects to your discovery document can do any of the following:

Identify the claims and grant types that you support
Retrieve the URLs of your introspection server and your JSON Web Keys
Determine which PKCE (Proof Key for Code Exchange) challenge methods you support

These can be done automatically, without requiring anyone to configure these values into the client. The OIDC clients can also obtain discovery documents on their own. Your well-known endpoint can always be reached by adding the string value /.well-known/openid-configuration to the end of your base domain, for example https://id.eu.nextreason.com/.well-known/openid-configuration.

Endpoint URL

Your well-known endpoint can always be reached by adding the string value /.well-known/openid-configuration to the end of your base domain, for example https://id.eu.nextreason.com/.well-known/openid-configuration.

Required Parameters

The /.well-known endpoint adheres to the OIDC authentication protocol. To view the parameters that must be and can be included in the discovery document, please refer to the official OIDC documentation.

Your specific parameters may vary depending on your configuration; if you're unclear on the parameters to use, please contact your Next Reason consultant.

Response Handling

The response is a JSON object containing various configuration details.

{
"issuer": "https://example.com",
"authorization_endpoint": "https://example.com/oauth2/auth",
"token_endpoint": "https://example.com/oauth2/token",
"userinfo_endpoint": "https://example.com/oauth2/userinfo",
"jwks_uri": "https://example.com/oauth2/certs",
"response_types_supported": ["code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"scopes_supported": ["openid", "profile", "email"],
"token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
"claims_supported": ["sub", "name", "email", "picture"]
}

Integration

Integrating a well-known endpoint to support OpenID Connect (OIDC) in a system or application involves fetching configuration information from the provider and using it to perform authentication and authorization operations.

Typical Steps to Use a Well-Known Endpoint

Discover the Configuration
Fetch the Configuration
Extract Necessary Endpoints and Metadata
Perform OIDC Flows
Implement Security Measures