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.
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.
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.
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.
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 the Admin API.
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 the Banno Back Office.
Usage as bearer token
API Requests must include the Access Token as a bearer token in the 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.
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.
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.
{
"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.
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).
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.
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.