Publishing Metadata

Table of Contents

Generating Authorization Server Metadata with Authlete

When publishing an OpenID Provider Metadata document using Authlete, you can use the API provided by Authlete: /api/service/configuration.

The response from this API can be used as metadata compliant with the following 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.