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 this RFC for more details on standard scopes and see this RFC for more details on standard claims.)

• openid (required)
  • Signals a request for OpenID Connect authentication and Identity Token.
• address (optional)
  • Adds the user’s address claim to the id_token including street_address, locality/city, region/state, and postal_code.
• email (optional)
  • Adds the user’s email claim to the id_token.
• phone (optional)
  • Adds the user’s phone number claim to the id_token.
• profile (optional)
  • Adds the user’s basic profile claims to the id_token including name, family_name, given_name, middle_name, preferred_username, picture, and locale.
• offline_access (optional)
  • Used to request a Refresh Token from the authentication server. Must be used in tandem with an authentication request parameter of prompt with a value of consent.
  • See this 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 API.
• https://api.banno.com/consumer/auth/offline_access
  • Used to request a Refresh Token from the authentication server. Does not require the prompt parameter to be present.
• https://api.banno.com/consumer/auth/transactions.detail.readonly
  • Retrieve user account information via the API.
• https://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 this 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 (includes client_id value)
• iat (required)
  • The time at which this ID Token was issued
• exp (required)
  • The time at which this ID Token expires
• iss (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 this 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 this RFC):

1. In the Identity Token
2. From the UserInfo Endpoint
3. 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 address
• birthdate - User’s birthdate
• email - User’s email address
• family_name - User’s last name
• given_name - User’s first name
• middle_name - User’s middle name
• name - User’s full name
• phone_number - User’s primary phone number
• picture - User’s profile picture URL
• preferred_username - User’s username
• https://api.banno.com/consumer/claim/cash_management_user - Cash Management user
• https://api.banno.com/consumer/claim/cash_management_user_id - Cash Management user ID
• https://api.banno.com/consumer/claim/devices - Authorized device information
• https://api.banno.com/consumer/claim/fi_routing_number - Institution routing number
• https://api.banno.com/consumer/claim/institution_assets - Institution assets
• https://api.banno.com/consumer/claim/institution_details - Institution details
• https://api.banno.com/consumer/claim/institution_id - Unique identifier for the institution
• https://api.banno.com/consumer/claim/masked_accounts - Accounts with masked account numbers
• https://api.banno.com/consumer/claim/netteller_id - NetTeller ID - Banks
• https://api.banno.com/consumer/claim/phone_numbers - Home, mobile, and work phone numbers
• https://api.banno.com/consumer/claim/theme_data - Theme data
• https://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 numbers
• https://api.banno.com/consumer/claim/cards - Debit and credit cards with full unmasked card numbers
• https://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 Unions
• https://api.banno.com/consumer/claim/external_tracking_records - SymXchange external tracking records
• https://api.banno.com/consumer/claim/id_documents - Identification documents information - Credit Unions
• https://api.banno.com/consumer/claim/loans - Loan records - Credit Unions
• https://api.banno.com/consumer/claim/shares - Share records - Credit Unions
• https://api.banno.com/consumer/claim/tax_id - User’s tax ID or social security number