Tokens
The Authentication Framework does not use API keys nor does it 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
An Access Token is obtained via the OAuth 2.0 Authorization Code Grant flow.
As part of the OAuth flow, third party apps will need to register API Credentials (i.e. client_id and client_secret). The back office administrator at your financial institution can do this for you in the External applications section of Banno People.
Usage as Bearer Token
API Requests must include the Access Token as a bearer token in the header.
Example
Authorization: Bearer [ACCESS_TOKEN]
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.
Example
{
"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.
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.
Example
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.