Tokens

Authentication Framework > Overview > Tokens

The Authentication Framework does not use API keys and does not share usernames and passwords with 3rd party developers.

Instead, it provides authorized access via an Access Token and provides authenticated user information via an Identity Token.

Access tokens

Authorized access is provided to third party apps via an Access Token.

The Access Token is encoded in JSON Web Token format.

Real world analogy

Think about Access Tokens as being like house keys, car keys, or similar. Anyone who possesses an Access Token can use it to access resources.

Example: Using an Access Token to access server resources via an API.

Obtaining an access token

Authorization code flow

An Access Token is obtained via the OAuth 2.0 Authorization Code Grant flow.

Authenticating to the Consumer API requires an External Application configuration to be created within Banno.

The back office administrator at your financial institution can do this for you in the External applications section of Banno People.

Understanding Your Development Experience

Are you a financial institution?

If you are a financial institution or working directly with a financial institution, you should work with the back office administrator at your institution to get appropriate access to Banno People.

Are you a fintech or independent developer?

If you are a fintech or other developer working without a financial institution, you are likely using the JackHenry.Dev developer portal. In this case, you will not have access to Banno People, however you will still have the ability to create and configure many aspects of your external application and plugin.

For more information on this, see our troubleshooting page.

Client credentials flow

An Access Token is obtained via the OAuth 2.0 Client Credentials flow.

Authenticating to the Admin API requires an External Application configuration to be created within Banno.

The back office administrator at your financial institution can do this for you in the Users & Groups section of Banno.

Understanding Your Development Experience

Are you a financial institution?

Are you a fintech or independent developer?

Usage as bearer token

API Requests must include the Access Token as a bearer token in the header.

Authorization header

Authorization: Bearer [ACCESS_TOKEN]

Lifetime

Each individual Access Token has its own specific lifetime of 10 minutes from when that specific token was issued.

The lifetime of an Access Token may change without notice.

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.

Obtaining an identity token

An Identity Token is obtained via the same OAuth 2.0 Authorization Code Grant flow used to obtain an Access Token, but with the addition of a scope parameter of openid. See the OpenID Connect and OAuth 2.0 topic for more details.

Usage

The Identity Token asserts the identity of the user and can be used similar to an identity card. The kind of information provided depends upon the scope parameters requested. See the OpenID Connect and OAuth 2.0 topic for more details.

Example decoded identity token

{
  "sub": "5cad5c30-6d24-11e9-870c-0242b78f8571",
  "aud": "05166b79-4f61-484d-a4b4-2a225926bf4b",
  "iat": 1571249648,
  "exp": 1571253248,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

Refresh tokens

When an Access Token becomes invalid or expires, a new one can be obtained via a Refresh Token.

Real world analogy

Think about Refresh Tokens as being like tokens used for a vending machine, laundromat, or similar.

The Refresh Token is exchanged for some other thing (i.e., an Access Token).

Example: Using a Refresh Token to exchange for a new Access Token.

Obtaining a refresh token

A Refresh Token can be requested from the authentication server by including the scope https://api.banno.com/consumer/auth/offline_access when initiating the OAuth 2.0 Authorization Code Grant flow.

See the OpenID Connect and OAuth 2.0 topic for more details on scopes.

Usage

A Refresh Token can be exchanged for a new Access Token by making a refresh request to the token endpoint and including the grant_type and refresh_token parameters.

Refresh token usage

grant_type=refresh_token
&refresh_token=PVOwQESPoMhjY7~THwVGl~ctZj5

Lifetime

Each individual Refresh Token has its own specific lifetime of 90 days from when that specific token was issued.

It is important to note that each Refresh Token is part of a chain of tokens. The chain can be extended out (one token at a time) until 1 year from the original issue date of the first Refresh Token. After 1 year, a new authorization flow would have to be initiated to start a new chain of Refresh Tokens.

Example

Each individual Refresh Token in a chain (e.g. RefreshToken-1, RefreshToken-2, RefreshToken-3, …RefreshToken-n) has its own specific lifetime of 90 days from when that specific token was issued. The chain has a lifetime of 1 year.

Public clients vs confidential clients

See the Glossary for information on the difference between Public Clients and Confidential Clients.

Public clients

Refresh Tokens issued to Public Clients are rotated on every use and a given token may only be used once.

Confidential clients

Confidential Clients are issued a Refresh Token on every use. However, old tokens are not invalidated and may continue to be used until their original expiration date. This allows Confidential Clients applications to obtain and utilize multiple Refresh Tokens at any given time.

Guide on refresh tokens

See our Guide on Refresh Tokens in the Consumer API docs.

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 Tue Jul 18 2023