Introduction

This article explains how an OpenID Provider (OP) or an Authorization Server (AS) can publish server metadata using the Authlete API.

Generating Authorization Server Metadata with Authlete

In OAuth and OpenID Connect, metadata is defined so that clients and relying parties (RPs) can obtain information about an authorization server.
Specifically, the relevant specifications are OpenID Connect Discovery and RFC 8414 OAuth 2.0 Authorization Server Metadata.

By using the /api/service/configuration API provided by Authlete, you can generate metadata that conforms to these two specifications.

OpenID Connect Discovery

An authorization server that supports OpenID Connect Discovery accepts GET requests at https://as.example.com/.well-known/openid-configuration, assuming https://as.example.com is used as the issuer.

In your authorization server implementation, you call Authlete’s /api/service/configuration API and return its response (optionally filtered or transformed) as JSON. An example call to /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 returned directly as a JSON string representing the 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"
  ],
  ...
}

OAuth 2.0 Authorization Server Metadata

For OAuth 2.0 clients, you can publish OAuth Server Metadata at 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 for this endpoint.

Metadata Caching and Operational Considerations

For both the OIDC Discovery document and OAuth Server Metadata, it is acceptable to implement caching on the authorization server or client side. When doing so, consider factors such as key rotation intervals and design an appropriate caching strategy.

Metadata Items Configurable via the Management Console

Some items configured in the Authlete Management Console are reflected in the response from the /api/service/configuration API. For example, the issuer identifier, various endpoint URLs, and supported authorization types configured in the console are automatically included in the API response.

For details on the specific configuration items included in the metadata, please refer to Service Configuration.

Selecting Which Metadata to Publish

Information returned by the /api/service/configuration API can be selectively included or excluded by the authorization server. For example, id_token_signing_alg_values_supported may include multiple algorithms supported by Authlete, but you may overwrite this value to publish only the algorithms intended for your authorization server.

Customizing Authlete Responses with JSON Patch

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

• Example: Restrict 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 apply your own custom logic to further modify the JSON after receiving it in your authorization server.