Claims in the Identity Token

In this guide, we will walk through these scenarios:

• Requesting a basic Identity Token
• Adding claims to the Identity Token
• Requesting different claims in the Identity Token versus the UserInfo endpoint

Prerequisites

To be successful, you will first need to understand how authentication works. Take a look at the Authentication (Command Line) Quickstart for a walkthrough of how to authenticate.

Requesting a basic identity token

These steps below are what it takes to request the most basic Identity Token possible. It will have the minimum required claims.

Send the user to the authorization URL

The authorization URL will be of the form:

https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/auth?client_id=[CLIENT_ID]
  &redirect_uri=[REDIRECT_URI]
  &scope=openid
  &response_type=code

Where:

• Using a scope value of openid requests that an Identity Token be issued.
• Other authorization URL parameters have been omitted for clarity.

Authentication response

Assume that the Authorization Code has been exchanged for an Access Token and an Identity Token.

The authentication server will respond with a JSON payload of the form:

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 3600,
  "id_token": "<lengthy-json-web-token-string>",
  "scope": "openid",
  "token_type": "Bearer"
}

The tokens are in JSON Web Token format.

Decoded identity token

After decoding the Identity Token it will look like this:

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "at_hash": "I0jclDRvksuJMtjq0RRWQg",
  "aud": "d784425f-43d2-40b3-92b1-3d87633121e6",
  "exp": 1658948860,
  "iat": 1658945260,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

Where:

• sub is the Subject Identifier that identifies this user.
• at_hash is a hash value.
• aud is the audience for this Identity Token (this is the Client ID).
• exp is the expiration time for this Identity Token.
• iat is the time at which the Identity Token was issued.
• iss is the identifier of the issuer of the Identity Token.

This is the most basic possible Identity Token.

Adding claims to the identity token

If you want to add more claims to an Identity Token, these are the necessary steps.

If you need to cross-reference a user to other system identifiers, this is most likely what you will use. See the Authentication Framework - Mapping Data to Other Systems topic for more details.

Let’s assume that you want the Unique Customer Identifier (which is either a CIF for a bank or Member Number for a credit union). This is an example of a Restricted Claim, which the financial institution must enable for your app.

The Unique Customer Identifier claim is identified with the special claim value of https://api.banno.com/consumer/claim/customer_identifier.

Let’s assume here that the financial institution has already enabled that Restricted Claim for our app.

Send the user to the authorization URL

The URL will be of the form:

https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/auth?client_id=[CLIENT_ID]
  &redirect_uri=[REDIRECT_URI]
  &scope=openid
  &response_type=code
  &claims={"id_token":{"https://api.banno.com/consumer/claim/customer_identifier":null}}

The claims parameter is constructed as a JSON object which then must be encoded.

Authentication response

Assume that the Authorization Code has been exchanged for an Access Token and an Identity Token.

The authentication server will respond with a JSON payload of the form:

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 3600,
  "id_token": "<lengthy-json-web-token-string>",
  "scope": "openid",
  "token_type": "Bearer"
}

The tokens are in JSON Web Token format.

Decoded identity token

After decoding the Identity Token it will look like this:

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "https://api.banno.com/consumer/claim/customer_identifier": "DAA0086",
  "at_hash": "5esY4ZIgkPqoD9wG4vSoWw",
  "aud": "d784425f-43d2-40b3-92b1-3d87633121e6",
  "exp": 1658959717,
  "iat": 1658956117,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

This has one more claim than the basic Identity Token.

• In this case, the example was from a bank, so the https://api.banno.com/consumer/claim/customer_identifier claim value is a CIF.
• If this same example was from a credit union then the https://api.banno.com/consumer/claim/customer_identifier claim value would be a member number.

If you added more claims such as name, address, phone_number, or email to the claims parameter in the authorization URL as {"id_token":{"name":null,"address":null,"phone":null,"email":null,"https://api.banno.com/consumer/claim/customer_identifier":null}, then the (decoded) Identity Token would look like this:

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "name": "Riley Doe",
  "address": {
    "locality": "Cedar Falls",
    "postal_code": "000050613",
    "region": "IA",
    "street_address": "123 Banno St."
  },
  "phone_number": "5558675309",
  "email": "rileydoe@jackhenry.dev",
  "https://api.banno.com/consumer/claim/customer_identifier": "DAA0086",
  "at_hash": "4SF_ruLqicwN52-g81KTqg",
  "aud": "d784425f-43d2-40b3-92b1-3d87633121e6",
  "exp": 1658964133,
  "iat": 1658960533,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

Requesting different claims in the identity token versus the UserInfo endpoint

Claims can be returned in these ways (as described in the RFC):

1. In the Identity Token
2. From the UserInfo Endpoint
3. In both the Identity Token and from the UserInfo Endpoint

This provides options for handling personally identifiable information (PII).

Imagine a situation where it is undesirable for Identity Tokens to contain PII data because those tokens are being stored by your service, yet it is still desirable to retrieve PII data on-demand via the UserInfo Endpoint.

The example below is similar to the Adding Claims to the Identity Token example, but it has been modified such that claims are returned by the UserInfo Endpoint, not in the Identity Token.

Send the user to the authorization URL

The URL will be of the form:

https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/auth?client_id=[CLIENT_ID]
  &redirect_uri=[REDIRECT_URI]
  &scope=openid
  &response_type=code
  &claims={"userinfo":{"name":null,"address":null,"phone_number":null,"email":null,"https://api.banno.com/consumer/claim/customer_identifier":null}}

Where:

• The claims parameter is constructed as a JSON object which then must be encoded.
• In this case, we use userinfo instead of id_token within the JSON object.

Authentication response

Assume that the Authorization Code has been exchanged for an Access Token and an Identity Token.

The authentication server will respond with a JSON payload of the form:

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 3600,
  "id_token": "<lengthy-json-web-token-string>",
  "scope": "openid",
  "token_type": "Bearer"
}

The tokens are in JSON Web Token format.

Decoded identity token

After decoding the Identity Token it will look like this:

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "at_hash": "3VHt8E5g1sf4jV-oKE-kkg",
  "aud": "d784425f-43d2-40b3-92b1-3d87633121e6",
  "exp": 1658965265,
  "iat": 1658961665,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

Notice that this Identity Token is the same as the Requesting a Basic Identity Token example.

Also notice that the Identity Token itself does not contain any PII.

UserInfo endpoint request using curl

If you still want to know information about the user, you can still get the information from the UserInfo endpoint.

curl --request GET \
  --url https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/me \
  --header 'authorization: Bearer [ACCESS_TOKEN]'

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "name": "Riley Doe",
  "address": {
    "locality": "Cedar Falls",
    "postal_code": "000050613",
    "region": "IA",
    "street_address": "123 Banno St."
  },
  "phone_number": "5558675309",
  "email": "rileydoe@jackhenry.dev",
  "https://api.banno.com/consumer/claim/customer_identifier": "DAA0086"
}

Next steps

Take a look at specific documentation in the API Reference.

Review concepts in the Authentication Framework - Tokens documentation.

Learn about scopes and claims in the Authentication Framework - OpenID Connect and OAuth 2.0 documentation.