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.