OpenID Connect and OAuth 2.0
OpenID Connect is an identity layer built on top of the OAuth 2.0 protocol.
Concept: Tokens
See Tokens.
Concept: Scopes and Claims
OAuth 2.0 has a concept of scopes, where authorization is based on limited access. Scopes define the categories of data that can be accessed and the operations that can be performed. See the RFC for more details on scopes.
OpenID Connect is built on top of the OAuth 2.0 protocol and adds the concept of claims, which are sets of authenticated information about the user that may be requested via specific scope values.
Scopes
Scopes typically control access and allow specific API endpoints to be called. Some scopes defined in the OpenID Connect specification have a special meaning and behavior.
Standard OpenID Connect Scopes
These are the standard OpenID Connect request scopes. See the RFC for more details on standard scopes. See the RFC for more details on standard claims.
openid
- Required: Signals a request for OpenID Connect authentication and Identity Tokenaddress
- Optional: Adds the user’s address claim to theid_token
includingstreet_address
,locality/city
,region/state
, andpostal_code
email
- Optional: Adds the user’s email claim to theid_token
phone
- Optional: Adds the user’s phone number claim to theid_token
profile
- Optional: Adds the user’s basic profile claims to theid_token
includingname
,family_name
,given_name
,middle_name
,preferred_username
,picture
, andlocale
offline_access
- Optional: Used to request a Refresh Token from the authentication server. Must be used in tandem with an authentication request parameter ofprompt
with a value ofconsent
. See the RFC for more details on Refresh Tokens.
Additional Scopes
These scopes may be optionally requested by an application.
https://api.banno.com/consumer/auth/accounts.readonly
- Retrieve account details and balances via the APIhttps://api.banno.com/consumer/auth/offline_access
- Used to request a Refresh Token from the authentication server. Does not require theprompt
parameter to be present.https://api.banno.com/consumer/auth/transactions.detail.readonly
- Retrieve user account information via the APIhttps://api.banno.com/consumer/auth/user.profile.readonly
- Retrieve user profile data such as name, address, email, phone number and picture via the API
Claims
Claims are specific values added to the id_token
or returned from the UserInfo endpoint.
The Consumer API - Guides - Claims in the Identity Token page has more information on selecting which claim values are added to the Identity Token or returned from the UserInfo endpoint.
Standard Claims
These are the standard claims about a user that would be returned in the Identity Token when openid
is included as a scope. See the RFC for more details on Identity Token claims.
sub
- Required: The unique subject identifier for the user. This value can be used where API calls use the placeholder{userId}
in API path definitions.aud
- Required: The audience for this ID Token (includesclient_id
value)iat
- Required: The time at which this ID Token was issuedexp
- Required: The time at which this ID Token expiresiss
- Required: The identifier for the issuer of the ID Token claims
Additional Claims
Additional claims are supported, but must be specifically requested utilizing the claims
parameter. See the RFC for details on the claims
parameter.
The claims
parameter is constructed as a JSON object which then must be encoded. The example below will return the same claims within both the Identity Token and from the UserInfo Endpoint.
const claimsToRequest = {
id_token: {
birthdate: null,
'https://api.banno.com/consumer/claim/customer_identifier': null,
},
userinfo: {
birthdate: null,
'https://api.banno.com/consumer/claim/customer_identifier': null,
},
};
const claimsParameterValue = encodeURIComponent(
JSON.stringify(claimsToRequest)
);
const authorizationCodeFlowUrl =
'https://digital.garden-fi.com/a/consumer/api/v0/oidc/auth?' +
'response_type=code&' +
'client_id=00000000-0000-0000-0000-000000000000&' +
'redirectUri=http%3A%2F%2Flocalhost%2Fcb&' +
'code_challenge=DVTX58LzHzAitSE8V9Pkkv0tCJsH8LOd5MkO6iCSgD8&' +
'code_challenge_method=S256&' +
'scope=openid&' +
'claims=' +
claimsParameterValue;
Claims can be returned in these ways (as described in the RFC):
- in the Identity Token
- from the UserInfo Endpoint
- in both the Identity Token and from the UserInfo Endpoint
This provides options for handling personally identifiable information (PII).
Imagine a situation where it is undesirable for Identity Tokens to contain PII data since those tokens are being stored by your service, yet it is still desirable to retrieve PII data on-demand via the UserInfo Endpoint.
The example below is similar to the prior example, but it has been modified such that claims are not returned in the Identity Token yet are returned by the UserInfo Endpoint.
const claimsToRequest = {
userinfo: {
birthdate: null,
'https://api.banno.com/consumer/claim/customer_identifier': null,
},
};
const claimsParameterValue = encodeURIComponent(
JSON.stringify(claimsToRequest)
);
const authorizationCodeFlowUrl =
'https://digital.garden-fi.com/a/consumer/api/v0/oidc/auth?' +
'response_type=code&' +
'client_id=00000000-0000-0000-0000-000000000000&' +
'redirectUri=http%3A%2F%2Flocalhost%2Fcb&' +
'code_challenge=DVTX58LzHzAitSE8V9Pkkv0tCJsH8LOd5MkO6iCSgD8&' +
'code_challenge_method=S256&' +
'scope=openid&' +
'claims=' +
claimsParameterValue;
Publicly Available Claims
These claims may be requested by any client application.
address
- User’s mailing addressbirthdate
- User’s birthdateemail
- User’s email addressfamily_name
- User’s last namegiven_name
- User’s first namemiddle_name
- User’s middle namename
- User’s full namephone_number
- User’s primary phone numberpicture
- User’s profile picture urlpreferred_username
- User’s usernamehttps://api.banno.com/consumer/claim/cash_management_user
- Cash Management userhttps://api.banno.com/consumer/claim/cash_management_user_id
- Cash Management user IDhttps://api.banno.com/consumer/claim/devices
- Authorized device informationhttps://api.banno.com/consumer/claim/fi_routing_number
- Institution routing numberhttps://api.banno.com/consumer/claim/institution_assets
- Institution assetshttps://api.banno.com/consumer/claim/institution_details
- Institution detailshttps://api.banno.com/consumer/claim/institution_id
- Unique identifier for the institutionhttps://api.banno.com/consumer/claim/masked_accounts
- Accounts with masked account numbershttps://api.banno.com/consumer/claim/netteller_id
- NetTeller ID - Bankshttps://api.banno.com/consumer/claim/phone_numbers
- Home, mobile, and work phone numbershttps://api.banno.com/consumer/claim/theme_data
- Theme datahttps://api.banno.com/consumer/claim/user_type
- User type
Restricted Claims
These claims contain potentially sensitive data. To request and obtain these claims, the 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.
https://api.banno.com/consumer/claim/accounts
- Accounts with full account numbershttps://api.banno.com/consumer/claim/cards
- Debit and credit cards with full unmasked card numbershttps://api.banno.com/consumer/claim/customer_identifier
- Unique customer identifier (CIF or Member Number)https://api.banno.com/consumer/claim/external_loans
- External loan records - Credit Unionshttps://api.banno.com/consumer/claim/external_tracking_records
- SymXchange external tracking recordshttps://api.banno.com/consumer/claim/id_documents
- Identification documents information - Credit Unionshttps://api.banno.com/consumer/claim/loans
- Loan records - Credit Unionshttps://api.banno.com/consumer/claim/shares
- Share records - Credit Unionshttps://api.banno.com/consumer/claim/tax_id
- User’s tax ID or social security number