Identifying "claims" expected to be included into an ID token

Preface


OpenID Connect (OIDC) allows a relying party (RP) to specify what claims it wants as an ID token, in its authentication requests.

Sometimes it would be complicated for an identity provider (OpenID provider; OP) to identify which claims are actually requested by the RP, due to methods to specify them.

This article describes how Authlete fulfills this process on behalf of the OP.

Identifying requested claims


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

Authlete parses the string and may identify claims that the RP expects to be included into an ID token. There are two types of claims; those indirectly specified by "scope" parameter and others directly specified by "claims" parameter. 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.

The OP checks the response from Authlete, determines which claims must be provided to the RP and prepares their values to be set to an ID token. It is done using Authlete's /auth/authorization/issue API. (See also: Adding claims to an ID token)
Claims in an authentication request and how Authlete detects them

Expanding shortcut scopes


OpenID Connect Core 1.0 Section 5.4 restricts that an OP shall not include claims derived from shortcut scopes (e.g., profile) into an ID token, when an access token is also to be issued.

Authlete is to follow this clause by default, i.e. it doesn't include the derived claims into the "claims" of /auth/authorization API response, when response_type is anything other than id_token (e.g., code). As a result, the OP will not set those claims as an ID token.

This setting can be changed via the "Claims Shortcut" in the Authlete service. The options are as follows:

  • Restrictive: In strict compliance with the clause, Authlete operates as described above. (default)
  • Nonrestrictive: Authlete always include the derived claims as the "claims" value, regardless of whether or not an access token is issued. The OP will decide whether to set those claims as an ID token.

Example


Assume that the RP requests 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 as follows. (folded for readability)

redirect_uri=...
 &response_type=code
 &client_id=...
 &nonce=...
 &scope=openid+profile
 &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

When the "Claim Shortcut" setting above is "Nonrestrictive," 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?