Authentication (Command Line)

The Consumer API uses OpenID Connect and OAuth 2.0 for authentication. This Quickstart guides you through making your first OpenID Connect authentication using the command line.

Not comfortable with curl, the command line, or prefer ready-to-run code? Try our Quickstart on Authentication (Node.js Example).

Want to learn more about Authentication? See the Authentication topic for more details.

Prerequisites

Before you get started, you’ll need to get these from the back office administrator at your financial institution who has access to Banno People.

If the administrator does not know where to do this, they can review the External application configuration article on the Banno Knowledge site.

• API Credentials
• User Account
• Configured Redirect URI

API Credentials

You’ll need API credentials to exercise the authorization flow. The Banno People administrator at your financial institution can provide you with a client_id and client_secret that you can use to access the Consumer API in your environment.

User Account

You’ll need a user account to exercise the authorization flow with a test user.

Configured Redirect URI

You’ll need to have a Redirect URI configured by your Banno People administrator. This is where the user’s browser will be redirected after the user has granted authorization.

Software Requirements

curl

If you don’t have the curl command line tool installed on your system already, you’ll need to install a version that is appropriate for your operating system.

Concept - Understanding the code_challenge and code_verifier Parameters

The Proof Key for Code Exchange extension adds additional security to the OAuth2 authorization code flow. The requesting app creates a secret (code_verifier) and submits a hash of that secret on the initial auth request. The secret itself is then submitted as part of the token exchange and ensures that the server exchanging the token is the same one that requested the authorization code.

Generating correct code_verifier and code_challenge values from the command line is difficult. It’s recommended to use an OAuth client that supports PKCE.

Generating a Code Verifier

A client simply needs to generate a random string of characters. The string must be at least 43 bytes long and no more than 128 bytes. It must be composed of only the following characters:

• English letters A-Z or a-z
• Numbers 0-9
• Symbols “-”, “.”, “_” or “~”.

Creating the Code Challenge

The code challenge is created by generating a SHA-256 byte hash of the code verifier. The result is then base64url-encoded.

Example Code Verifier and Code Challenge Creation

const crypto = require('crypto');
const codeVerifier = crypto
  .randomBytes(60)
  .toString('hex')
  .slice(0, 128);
const codeChallenge = crypto
  .createHash('sha256')
  .update(Buffer.from(codeVerifier))
  .digest('base64')
  .replace(/=/g, '')
  .replace(/\+/g, '-')
  .replace(/\//g, '_');

To check your work, use this code_verifier and ensure you get the listed code_challenge:

code_verifier=e517c32aee2356891326604e79ad7d358154e124c157d762cbc8896fb13bfbc5d93a335cc27df714a9280e8249cbc3507143b3b7829d3fe9f62b9fce
code_challenge=4lKn4LVhzJzjx_BttEPuMcracgFKVKbTMmSKYAvA24Y

Check your work: Paste in a verifier or hit the create button to generate one.

1. Get Authorization from the User

Send the user to the Authorization URL

The URL will be of the form:

https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/auth?client_id=[CLIENT_ID]
  &redirect_uri=[REDIRECT_URI]
  &scope=[SCOPES]
  &response_type=code
  &state=[STATE]
  &code_challenge=[CODE_CHALLENGE]
  &code_challenge_method=S256

Where:

• CLIENT_ID is the client_id from your API credentials.
• REDIRECT_URI is the configured Redirect URI where the user’s browser will be redirected after the user has granted authorization.
• SCOPES is one or more scopes. The openid scope is required to initiate an OpenID Connect request.
• STATE is an opaque, non-guessable value generated by the client to prevent Cross-site request forgery (CSRF) attacks. This enables the client to verify the validity of the request.
• CODE_CHALLENGE is the PKCE code challenge value.

Get the Authorization Code from the Redirect

The redirect will be of the form:

[REDIRECT_URI]?code=[CODE]&state=[STATE]

Where:

• REDIRECT_URI is the configured Redirect URI.
• CODE is an authorization code that can be exchanged for an access token.
• STATE is the client-generated value passed in to the authorization URL.

2. Exchange the Authorization Code for an Access Token

Request using curl

Use curl to make an HTTP POST request of the form:

curl -v --request POST \
  --url https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=[CLIENT_ID] \
  --data client_secret=[CLIENT_SECRET] \
  --data grant_type=authorization_code \
  --data 'code=[CODE]' \
  --data redirect_uri=[REDIRECT_URI] \
  --data code_verifier=[CODE_VERIFIER]

Where:

• CLIENT_ID is the client_id.
• CLIENT_SECRET is the client_secret from your API credentials.
• CODE is the authorization code from the previous step.
• REDIRECT_URI is the configured Redirect URI.
• CODE_VERIFIER is the PKCE code verifier value.

Authentication Response

The authentication server will respond with a JSON payload of the form:

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 3600,
  "id_token": "<lengthy-json-web-token-string>",
  "scope": "openid",
  "token_type": "Bearer"
}

Where:

• access_token is the access token in JWT (JSON Web Token) format.
• expires_in is the amount of time (in seconds) for which the access token is valid.
• id_token is the identity token in JWT (JSON Web Token) format.
• scope is the set of scopes authorized by the user.
• token_type is the type of token (the string “Bearer”).

Token Formats

The Access Token and Identity Token are encoded in JWT (JSON Web Token) format. When they are decoded, they will look similar to the forms described below.

Access Token

The Access Token contains authorization information about your application regarding which actions it is allowed to perform via the Consumer API. These actions map to the scopes (e.g. openid).

{
  "jti": "_Prnud9uU6S1Gjd_z_x0n",
  "sub": "5cad5c30-6d24-11e9-870c-0242b78f8571",
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc",
  "iat": 1591056386,
  "exp": 1591059986,
  "scope": "openid",
  "aud": "55fc6a69-a4dd-404c-97f9-e2361b4c44b1"
}

Identity Token

The Identity Token contains authentication information about the user (i.e. claims).

{
  "sub": "5cad5c30-6d24-11e9-870c-0242b78f8571",
  "nonce": "qe8zu0qoi5h",
  "at_hash": "xAaATGqdRxgZ4wiSVSjSPw",
  "sid": "68530fe4-bd6e-412d-bac7-6970aa74fecc",
  "aud": "55fc6a69-a4dd-404c-97f9-e2361b4c44b1",
  "exp": 1591059986,
  "iat": 1591056386,
  "iss": "https://digital.garden-fi.com/a/consumer/api/v0/oidc"
}

See the RFC for more details on Identity Token claims.

The sub (Subject Identifier) claim is of particular importance when using the Consumer API as you’ll use this when the API path includes a {userId} reference.

Next Steps

Congratulations! Continue your learning journey:

• Overview
• API Reference
• Guide: Refresh Tokens