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.

WARNING

This example assumes that you have a working familiarity with the cURL command line tool.


Prerequisites

Before you get started, you’ll need to get access to the back office from the 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.

If you are developing using a Jack Henry test environment, you will not have access to Banno Users & Groups. In this case, Jack Henry is the acting administrator of the financial institution and you will have to contact us for any Banno Users & Groups operations.

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

NodeJS example
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:

Valid output

code_verifier=e517c32aee2356891326604e79ad7d358154e124c157d762cbc8896fb13bfbc5d93a335cc27df714a9280e8249cbc3507143b3b7829d3fe9f62b9fcecode_challenge=4lKn4LVhzJzjx_BttEPuMcracgFKVKbTMmSKYAvA24Y

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

code_verifier
code_challenge

1) Get Authorization from the User

Send the user to the Authorization URL

The URL will be of the form:

Authorization

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 URL 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 token post
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:

Token Response
{
  "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:


Have a Question?
Have a how-to question? Seeing a weird error? Get help on StackOverflow.
Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.
Last updated Fri Oct 28 2022