OpenID Connect Discovery

The OpenID Connect Discovery endpoint provides metadata about the OpenID Provider's configuration. This endpoint allows clients to dynamically discover information needed to interact with the authorization server.

Endpoint

GET /.well-known/openid-configuration/w/[tenant]/[project]

This endpoint returns the OpenID Provider's configuration metadata.

Response

If the request is successful, the server will respond with a 200 OK status code and a JSON document containing the provider's metadata:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "http://api.haste.health/",
  "authorization_endpoint": "http://api.haste.health/w/ohio-health/system/api/v1/oidc/auth/authorize",
  "jwks_uri": "http://api.haste.health/w/ohio-health/system/api/v1/oidc/certs/jwks",
  "token_endpoint": "http://api.haste.health/w/ohio-health/system/api/v1/oidc/auth/token",
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "offline_access"
  ],
  "response_types_supported": [
    "code",
    "id_token",
    "id_token token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "subject_types_supported": [
    "public"
  ]
}

Key Metadata Fields

Required Fields

• issuer - The authorization server's identifier (must match the iss claim in issued tokens)
• authorization_endpoint - URL of the OAuth 2.0 authorization endpoint
• token_endpoint - URL of the OAuth 2.0 token endpoint
• jwks_uri - URL of the JSON Web Key Set document
• response_types_supported - List of supported OAuth 2.0 response types
• subject_types_supported - List of subject identifier types supported (public, pairwise)
• id_token_signing_alg_values_supported - List of JWS signing algorithms supported for ID tokens

Optional Fields

• userinfo_endpoint - URL of the UserInfo endpoint
• registration_endpoint - URL of the dynamic client registration endpoint
• scopes_supported - List of OAuth 2.0 scopes supported
• response_modes_supported - List of OAuth 2.0 response modes supported
• grant_types_supported - List of OAuth 2.0 grant types supported
• token_endpoint_auth_methods_supported - List of client authentication methods supported
• claims_supported - List of claim names supported
• code_challenge_methods_supported - List of PKCE code challenge methods supported
• introspection_endpoint - URL of the token introspection endpoint
• revocation_endpoint - URL of the token revocation endpoint
• end_session_endpoint - URL of the logout/end session endpoint

Error Handling

If there are any issues retrieving the configuration, the server will respond with an appropriate error status code:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "server_error",
  "error_description": "Unable to retrieve OpenID configuration"
}

Example using cURL

Here is an example of how to retrieve the OpenID Connect discovery document using cURL:

curl -X GET "http://api.haste.health/.well-known/openid-configuration/w/[tenant]/[project]" \
     -H "Accept: application/json"

This command sends a GET request to retrieve the OpenID Provider's configuration metadata.

Using the Discovery Document

Clients should use this endpoint to dynamically discover the authorization server's capabilities and endpoint URLs. This enables:

1. Dynamic configuration - Clients don't need hardcoded endpoint URLs
2. Capability discovery - Clients can check which features are supported
3. Algorithm negotiation - Clients can select appropriate signing algorithms
4. Scope discovery - Clients can discover available scopes

Example client initialization:

// Fetch and parse discovery document
const response = await fetch('http://api.haste.health/.well-known/openid-configuration/w/[tenant]/[project]');
const config = await response.json();

// Use discovered endpoints
const authUrl = `${config.authorization_endpoint}?${params}`;
const tokenUrl = config.token_endpoint;
const jwksUri = config.jwks_uri;