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.
Map Banno’s user identifier to Banno’s APIs
This is an example of the most basic possible Identity Token.
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:
- 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:
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:
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.
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/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:
Similarly, this is what the result would look like for a credit union:
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.