Publishing OpenID Connect Discovery Metadata

Table of Contents

Generating Authorization Server Metadata with Authlete

When an authorization server publishes server metadata compliant with OpenID Connect Discovery 1.0, you can use the /api/service/configuration API provided by Authlete.

The response from this API can be used as metadata compliant with the following specifications.

OpenID Connect Discovery

An ID token issuing server that supports OpenID Connect Discovery 1.0 accepts GET requests at
https://as.example.com/.well-known/openid-configuration when https://as.example.com is used as the issuer.

The authorization server implementation calls Authlete’s /api/service/configuration API and returns the response (optionally selected and/or transformed as needed) as JSON. An example of calling /api/service/configuration is shown below.

curl --request GET \
  --url 'https://jp.authlete.com/api/<serviceId>/service/configuration?pretty=true' \
  --header 'authorization: Bearer <serviceAccessToken>' \
  --header 'content-type: application/json'

The response is a JSON string containing metadata.

{
  "issuer": "https://as.example.com",
  "authorization_endpoint": "https://as.example.com/api/authorization",
  "prompt_values_supported": [
    "none",
    "login",
    "consent",
    "select_account",
    "create"
  ],
  "token_endpoint": "https://as.example.com/api/token",
  "userinfo_endpoint": "https://as.example.com/api/userinfo",
  "jwks_uri": "https://as.example.com/api/jwks",
  "scopes_supported": [
    "address",
    "email",
    "openid",
    "offline_access",
    "phone",
    "profile",
    "edit_payment_methods",
    "grant_management_query",
    "grant_management_revoke"
  ],
  ...
}

The authorization server can return Authlete’s response directly to clients.

OAuth 2.0 Authorization Server Metadata

For OAuth 2.0 clients, you can publish OAuth Server Metadata at a URI such as
https://as.example.com/.well-known/oauth-authorization-server in accordance with RFC 8414.

As with OIDC Discovery, the response from the /api/service/configuration API can also be used at this endpoint.

Caching and Operational Considerations for Publishing Metadata

For OIDC Discovery documents and OAuth Server Metadata, caching may be implemented on the authorization server and/or client side. Please consider appropriate cache implementations based on factors such as key rotation periods.

Metadata Items Configurable in the Management Console

Some items configured in the Authlete management console are reflected in the response from the /api/service/configuration API. For example, settings such as the issuer identifier and various endpoints (e.g., the authorization endpoint), as well as supported authorization types, are automatically reflected in the /api/service/configuration API response. For details on the specific configuration items included in metadata, please refer to Service Settings.

Selecting Which Items to Publish

Information returned by the /api/service/configuration API can be selectively chosen by the authorization server. For example, although Authlete returns multiple supported algorithms for id_token_signing_alg_values_supported, you may overwrite this value with those intended by the authorization server before publishing.

Customizing Authlete Responses with JSON Patch

Authlete allows customization of the /api/service/configuration API response based on RFC 6902 JSON Patch.

Example: Restricting id_token_signing_alg_values_supported to ["RS256"] only

curl --request GET \
  --url 'https://jp.authlete.com/api/<serviceId>/service/configuration?patch=%5B%7B%22op%22%3A%20%22replace%22%2C%20%22path%22%3A%20%22%2Fid_token_signing_alg_values_supported%22%2C%20%22value%22%3A%20%5B%22RS256%22%5D%7D%5D' \
  --header 'authorization: Bearer <serviceAccessToken>' \
  --header 'content-type: application/json'

You can also customize the received JSON using your own logic on the authorization server side.

Publishing jwks_uri