Using Bearer Authentication

Overview

Bearer authentication uses an encrypted token to authorize and authenticate with the RESTful API. Unlike Basic authentication, Bearer authentication offers a more secure means of sending API calls by not requiring the client to store or send fixed user credentials with each call.

To use Bearer authentication with the RESTful API, you must first generate an API key in Automate, encrypt your own token, and then add the encrypted Bearer token to the authorization header for API calls.

Unencrypted token format

The format of the unencrypted Bearer token consists of the Token salt + API key + Date and time stamp components encoded in Base64:

1. Token salt - The first eight characters of the token are the "salt." These are random characters specified by you.

   EXAMPLE: wJwWCw==

2. API key - The next 32 characters of the token are the API key you generated in Automate for the users and user groups that will call the RESTful API.

   EXAMPLE: mzalkUoWr0ixVhSjRRHnaXAX1htTO+lM

3. Date and time stamp - The last 20 characters of the token are an ISO 8601-formatted UTC date and time stamp for when the request was sent using the following format: YYYY-MM-DD hh:mm:ssZ.

   EXAMPLE: 2024-04-22 16:06:42Z

Encryption

The token must be encrypted using the following:

Derived key

Use the following parameters in a library of your choice (for example, Rfc2898DeriveBytes(Byte[] passphrase, Byte[] salt, int iterations) in C# or CryptoJS.PBKDF2(passphrase, keySalt, {keysize:256, iterations:1000}) in JavaScript):

• Passphrase (Base64 encoded) - iS68kp&5jH%ss79H{730D415

• Key salt - Use the following byte array: [1,2,3,4,5,6,7,8]

• Encryption iteration - 1000

Algorithm

Use the following encryption algorithm in a library of your choice (for example, AesCryptoServiceProvider in C# or CryptoJS.AES.encrypt in JavaScript):

• Encryption standard - AES-256-CBC

• KeySize - 256

• BlockSize - 128

• Key - First 32 bytes of the derived key

• Initialization vector (IV) size - First 16 bytes of the derived key

Authorization header

Add the encrypted Bearer token to the authorization header to send API calls to the RESTful API.

Example script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
//  *** Set the variables before running 

// Import and activate CryptoJS
const cryptojs = require('crypto-js');
// Import integrated NodeJS string_decoder
const { StringDecoder } = require('string_decoder');

// API Key is created in Automate and Passphrase is given
const apikey = pm.collectionVariables.get('APIKey');
const passphrase = pm.collectionVariables.get('Passphrase');

const decoder = new StringDecoder('utf8');
// Creates 8-bit unsigned integers with an array value of [1,2,3,4,5,6,7,8]
// This is to be used as the key salt
const u8 = new Uint8Array([1,2,3,4,5,6,7,8]);
const bufferU8 = Buffer.from(u8);
let decodedU8 = decoder.write(bufferU8)
decodedU8 = Buffer.from(decodedU8).toString('base64')
// Encodes the Int Array to Base64
const keySalt = cryptojs.enc.Base64.parse(decodedU8);

// Generate the 256-bit encryption key using the provided passphrase
var output = CryptoJS.PBKDF2(passphrase, keySalt, {
    keySize: 256,
    iterations: 1000
});

// The underlying words array might have more content than was asked: remove insignificant words
output.clamp();

// Set the salt
const saltBytes = cryptojs.lib.WordArray.random(4);
const saltString = cryptojs.enc.Base64.stringify(saltBytes);

// Set date format 
// Note 20 characters including the space
const date = new Date().toISOString();
const dateformat1 = date.substring(0, 10);
const dateformat2 = date.substring(11, 19);
const datetime = dateformat1 + ' ' + dateformat2 + 'Z';

// Set the AES encryption key and initialization vector from the PBKDF2 encryption key bytes
const key = cryptojs.lib.WordArray.create(output.words.slice(0, 256/32));
const iv  = cryptojs.lib.WordArray.create(output.words.slice(256/32, (256+128)/32));

// Create and encrypt the string
const cryptString = saltString + apikey + datetime;
const encryptedBytes = cryptojs.AES.encrypt(cryptString, key, {
    iv: iv
});
const encryptedString = encryptedBytes.toString();

// Add the token to the outgoing header
const headerToken = 'Bearer ' + encryptedString;
pm.request.headers.add({ key: 'Authorization', value: headerToken });
console.log("Bearer Token value " ,headerToken); 
pm.environment.unset("variable_key");

Related Topics