How to call the well-known endpoint for the discovery document

The OpenID Connect (OIDC) discovery document, commonly referred to as the well-known endpoint, provides OIDC clients with the necessary configuration data to interact with your Next Identity implementation. It simplifies integration by allowing clients to automatically retrieve important metadata, such as endpoint URLs, supported claims, and security settings.

Using the discovery document helps ensure clients are properly configured for secure and reliable authentication flows—without requiring manual setup.

Before using the well-known endpoint:

• Ensure your OIDC client is capable of dynamic discovery

• Identify the base domain of your Next Identity environment (e.g., https://id.eu.nextreason.com)

• Confirm network access to the endpoint URL

If you're unsure of your base domain or configuration, contact the Next Reason Support team.

To access the discovery document, append the following path to your identity domain:

/.well-known/openid-configuration 

Example:

https://id.eu.nextreason.com/.well-known/openid-configuration 

This endpoint returns a standardized JSON response that includes all required OIDC metadata.

Make an HTTP GET request to the endpoint using your preferred method (e.g., browser, HTTP client, or application code):

https://id.eu.nextreason.com/.well-known/openid-configuration 

The response will look similar to this:

{   
"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"],   
"scopes_supported": ["openid", "profile", "email"],   
"claims_supported": ["sub", "name", "email", "picture"],   "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],   
"id_token_signing_alg_values_supported": ["RS256"] 
} 

Your client should parse the JSON and use the relevant values to configure itself:

• authorization_endpoint: Start of the OIDC flow

• token_endpoint: Exchange authorization code for tokens

• jwks_uri: Public keys used to validate tokens

• scopes_supported and claims_supported: Define user permissions and attributes

• response_types_supported: Determine how tokens are returned

This automatic setup ensures that the client dynamically aligns with the server’s current configuration, minimizing setup errors and maintenance.

Once configured, your client can initiate OIDC flows (e.g., authorization code flow with PKCE) using the endpoints and settings retrieved from the document. This includes:

• Redirecting users to the authorization_endpoint

• Handling responses and exchanging tokens at the token_endpoint

• Validating ID tokens using keys from the jwks_uri

• See the other guides on each endpoint for integration tips

• Use TLS for all communication

• Regularly refresh the discovery document if you cache it

Once integrated, your application can authenticate users using OIDC, with minimal configuration and improved security. Updates made to the identity platform’s metadata will automatically be picked up by your client if it supports dynamic discovery.