Authentication

This Quickstart guides you through making your first Client Credentials flow authentication using our command line utility, @jkhy/banno-client-creds-helper.

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


Prerequisites

Before you get started, you’ll need the following:

  • The back office administrator at your financial institution who has access to the Users & Groups section of Banno

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

Software Requirements

OpenSSL

This Quickstart uses OpenSSL commands to generate a Public Key + Private Key pair.

Node.js, npm, nvm

The @jkhy/banno-client-creds-helper utility is built for Node.js and npm.

If you don’t have these installed on your system already, you may want to install a Node Version Manager such as nvm.

The utility requires Node.js version 14.0.0 or later.

Check your current version with node --version.


Generating a Public Key + Private Key pair

For more details, see the Public Key + Private Key topic.

1) Create the Private Key

Command Line
openssl genpkey -algorithm RSA -out private.pem

2) Create the Public Key in .PEM format

Command Line
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Configuration in Users & Groups section of Banno

For more details, see the Configuration topic.

These steps will need to be performed by the back office administrator at your financial institution.

1) Enter a Name for the application

Enter a name of Test Application .

2) Select an Application Type

Select Service account.

3) Copy-and-paste the Public Key

Copy the contents of the public.pem Public Key file created in the earlier steps.

You can use the command below to put the public key directly into your clipboard.

Command Line
pbcopy < public.pem

Paste the contents into the text field.

4) Select the Associated User

Select the Associated User for this application. The Associated User should have only the privileges/permissions that are specifically necessary for the application to function.

If this user does not exist, then it’ll have to be created by the back office administrator at your financial institution.

5) Click Save

Click the Save button to create the configuration of the API credentials.

This will generate the Client ID necessary for the next step.


Obtain an Access Token

For more details, see the Client Credentials Flow topic.

You’ll need the following from the previous steps to run the @jkhy/banno-client-creds-helper utility:

  • Client ID
  • private.pem Private Key file
Command Line
npx @jkhy/banno-client-creds-helper client-assertion --client-id=[CLIENT_ID] --private-key=./private.pem

The npx command automatically downloads and executes the latest version of the utility on-demand.

The terminal will output the various steps that the @jkhy/banno-client-creds-helper performs:

  • Creating the JWT payload
  • Signing the JWT
  • Sending the Token Request

You’ll know that you have successfully authenticated based on this part of the terminal output:

Example success response
[content omitted]
Token POST response: {
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 600,
  "token_type": "Bearer",
  "scope": "openid full"
}

When decoded, the Access Token will look similar to the form below:

Decoded Access Token
{
  "authType": "e",
  "v": "0",
  "clientName": "Test Application",
  "institutionId": "[INSTITUTION_ID]",
  "accountId": "[ACCOUNT_ID]",
  "jti": "7ZGJ4E2HBgXlVrA2jhoMo",
  "iat": 1624985060,
  "exp": 1624985660,
  "scope": "openid full",
  "iss": "https://www.banno.com/a/oidc-provider/api/v0",
  "aud": "[CLIENT_ID]"
}

The Access Token can be used to make API calls.

The Authentication Framework - Tokens article has information on the various Tokens.


Next Steps

Congratulations! Continue your learning journey: