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 )

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 null%2c
%22email\_verified%22%3a null%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"
]

Proprietary claims such as “http://example.info/claims/category" have to be added to “Supported Claims” of Authlete’s service instance used as a backend of the OP.

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.