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

More documentation about the various types of tokens can be found in the Authentication Framework - Tokens documentation.


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 URL will be of the form:

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

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:

Token Response
{
  "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:

Decoded Identity Token
{

  "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.

With this basic Identity Token, we have the Subject Identifier which we can use as the User ID parameter for the Consumer API (see the API Reference for details).


Adding Claims to the Identity Token

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

If you wanted to cross-reference a user to other system identifiers, this is most likely what you would use. See Authentication Framework - Mapping Data to Other Systems 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 requires a financial institution to 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.

Assume that the financial institution has enabled that Restricted Claim for our app.

Send the user to the Authorization URL

The URL will be of the form:

Authorization
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:

Token Response
{
  "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:

Decoded Identity Token
{

  "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:

Decoded Identity 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",
  "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 not returned in the Identity Token yet are returned by the UserInfo Endpoint.

Send the user to the Authorization URL

The URL will be of the form:

Authorization
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}}

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:

Token Response
{
  "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:

Decoded Identity Token
{

  "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, then you can still get the information from the UserInfo endpoint.

Curl token post
curl --request GET \
  --url https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/me \
  --header 'authorization: Bearer [ACCESS_TOKEN]'
UserInfo Endpoint Response
{
  "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.