Map Customer Identities to Existing System IDs

Authentication Framework > Guides > Map Customer Identities to Existing System IDs

In this guide, we will walk through these scenarios:

How to map Banno’s user identifier to Banno’s APIs
How to use claims about the user to cross-reference users in other apps
How to identify a user in other systems at a bank or credit union

Prerequisites

To be successful, you will first need to understand how to request specific claims in the Identity Token. Take a look at the Claims in the Identity Token guide for a walkthrough of how to request specific claims in the Identity Token.

Review of Identity Tokens

Authenticated identity information about a user is provided to third party apps via an Identity Token.

The Identity Token is encoded in JSON Web Token format.

Real world analogy

Think about Identity Tokens as being like a driver’s license, passport, or similar. The information in the Identity Token is about a single individual.

Example: Using an Identity Token to cross-reference a user to the Consumer API, a hypothetical loan application, or an existing system identifier in a database.

Map Banno’s user identifier to Banno’s APIs

This is an example of the most basic possible Identity Token.

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

Every Identity Token includes a sub claim—also known as the Subject Identifier—which uniquely identifies the user within the given financial institution.

In this example, the value of the sub claim is e58dc9d6-0acb-4770-b719-93fe675f652b.

You can pass that value as the User ID parameter in calls to the Consumer API or Admin API.

For example, the {userId} parameter can be replaced by the value of the sub claim in the Consumer API’s GET /users/{userId}/accounts endpoint to become GET /users/e58dc9d6-0acb-4770-b719-93fe675f652b/accounts.

Similarly, the {userId} parameter can be replaced by the value of the sub claim in the Admin API’s GET /a/consumer-status/api/v0/users/{userId}/status endpoint to become GET /a/consumer-status/api/v0/users/e58dc9d6-0acb-4770-b719-93fe675f652b/status.

Use claims about the user to cross-reference users in other apps

Imagine a hypothetical scenario where you need to need to cross-reference the user in another app.

In this scenario, imagine that you need to collect these bits of information about the user:

email
phone
address
Tax ID / SSN

The email, phone, and address are examples of standard OpenID Connect claims which are publicly available which can be requested by any developer.

Adding those claims to the authorization request would result in an Identity Token which looks like this example:

Decoded Identity Token

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "address": {
    "locality": "Cedar Falls",
    "postal_code": "000050613",
    "region": "IA",
    "street_address": "123 Banno St."
  },
  "phone_number": "5558675309",
  "email": "rileydoe@jackhenry.dev",
  "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"
}

However, in this hypothetical scenario you still need to retrieve the user’s Tax ID / SSN.

You might read the docs and realize that you can add the https://api.banno.com/consumer/claim/tax_id restricted claim to the authorization request. However, merely adding that claim to the authorization request is not sufficient to add that claim to the Identity Token.

The restricted claims contain potentially sensitive data. To request and obtain these claims, the External Application must specifically be configured to allow them. The back office administrator at your financial institution can do this for you in the External applications section of Banno People.

Assuming that the https://api.banno.com/consumer/claim/tax_id restricted claim has been enabled for your External Application, adding that claim to the authorization request would result in an Identity Token which looks like this example:

Decoded Identity Token

{
  "sub": "e58dc9d6-0acb-4770-b719-93fe675f652b",
  "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/tax_id": "207003900",
  "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"
}

Identify a user in other systems at a bank or credit union

These are common ways to identify a user within the systems at a financial institution:

For banks, that would be a CIF record.
For credit unions, that would be a Member Number.

The https://api.banno.com/consumer/claim/customer_identifier restricted claim is a single claim which will return either a CIF for a bank or a Member number for a credit union.

However, merely adding that claim to the authorization request is not sufficient to add that claim to the Identity Token.

Assuming that the https://api.banno.com/consumer/claim/customer_identifier restricted claim has been enabled for your External Application, adding that claim to the authorization request would result in an Identity Token which looks like this example for a bank:

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

Similarly, this is what the result would look like for a credit union:

Decoded Identity Token

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

Next steps

Review concepts in the Authentication Framework - Tokens documentation.

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

Have a Question?

Have a how-to question? Seeing a weird error? Get help on StackOverflow.

Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.

Last updated Thu Nov 9 2023