Authentication - Authorization Code (Command Line)

The Admin API uses OpenID Connect and OAuth 2.0 for authentication.

This Quickstart guides you through making your first Authorization Code flow authentication using the command line.

Prerequisites

Before you get started, you’ll need to get the following from the back office administrator at your financial institution who has access to Users & Groups.

• External Applications with API Credentials
• Configured Redirect URI (OAuth Debugger is a great option if you just want to test quickly.)

If the administrator does not know where to do this, they can review the Configuration topic.

API credentials

You’ll need API credentials to exercise the authorization flow. The External Application you create will have a client_id and client_secret that you will use.

Configured Redirect URI

You’ll need to have a Redirect URI configured in your External Application. 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.

Step 1. Get authorization from the user

Send the user to the authorization URL

The URL will be of the form:

https://banno.com/a/oidc-provider/api/v0/auth?client_id=[CLIENT_ID]
  &redirect_uri=[REDIRECT_URI]
  &response_type=code
  &scope=[SCOPES]
  &code_challenge=[CODE_CHALLENGE]
  &code_challenge_method=S256
  &state=[STATE]

Where:

• CLIENT_ID is the client_id from your API credentials.
• REDIRECT_URI is the configured Redirect URI where the browser will be redirected after authorization is granted.
• SCOPES is one or more . The openid scope is required to initiate an OpenID Connect request. To see all currently supported scopes, navigate to Admin API OpenID Configuration.
• 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.

Step 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://banno.com/a/oidc-provider/api/v0/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_at": "<ISO date format>",
  "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_at an ISO date format expiration
• 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”).

Next steps

Congratulations! Continue your learning journey:

• Overview
• API Reference