Detecting "claims" expected to be included into ID token

Preface


Authlete's /auth/authorization API can parse OIDC authentication request from a relying party (RP) and detect claims that the RP is asking OpenID provider (OP) to include into an ID token.

The OP will be preparing appropriate values for the claims, based on the result of the detection, and setting the claim/value pairs to the ID token by making a request to Authlete's /auth/authorization/issue API.

This article describes how Authlete detects the expected claims and responds to the OP.

Detecting claims requested by RP


Once the OP receives an OIDC authentication request from the RP through user agent (Web browser), it makes a request to Authlete's /auth/authorization API to parse query string of the authentication request.

Authlete parses the string and may detect claims that the RP expects to be included into an ID token. There are two types of claims; those indirectly specified by "scope" and others directly specified by "claims." Authlete expands the former ones and aggregates together with the latter ones.

Then Authlete makes an API response to the OP, including "claims" whose values include the claims (e.g. email) that the OP is expected to set explicitly. Note that the "claims" in the response doesn't include ones which Authlete is responsible for setting by default.

For example, the RP would request the following scope and claims:

  • Scope (excluding the "openid" scope): 
    • profile
  • Claims that the RP expects to include into an ID token: 
    • http://example.info/claims/category
    • email_verified

Query string of the authentication request form the RP would be:

redirect_uri=https://client.example.org/cb/example.com&response_type=code&client_id=13691914910051&scope=openid+profile&nonce=n-0S6_WzA2Mj&claims=%7b%22id_token%22%3a%7b%22http%3a%2f%2fexample%2einfo%2fclaims%2fcategory%22%3a%20null%2c%22email_verified%22%3a%20null%7d%7d

Once the OP receives this string as the authentication request and sends it (as a value of "parameters") to Authlete's /auth/authorization API,  the OP would receive an API response including the following "claims." Note that there are other claims which are indirectly specified by the "profile" scope. (folded for readability)

  "claims": [
    "birthdate",
    "email_verified",
    "family_name",
    "gender",
    "given_name",
    "http://example.info/claims/category",
    "locale",
    "middle_name",
    "name",
    "nickname",
    "picture",
    "preferred_username",
    "profile",
    "updated_at",
    "website",
    "zoneinfo"
  ],



The values included in "claims" here are only those that are expected to be explicitly specified in another "claims" parameter of a request to /auth/authorization/issue API.

For example, "sub" is a essential claim for an ID token. Authlete is to generate an appropriate value of the claim from"subject" parameter in a request to /auth/authorization/issue API, and set it to "sub" in the ID token. In other words, the OP must not specify it as "claims" in the request to /auth/authorization/issue API. Thus such claims don't be shown in "claims" of the response from /auth/authorizatoin API.
How did we do with this article?