Authentication Token

To authenticate with other systems, Alma sometimes uses a JSON Web Token (JWT). The token is signed with the RS256 algorithm. See below for examples of how to validate the token signature.

Validation Examples

Validating the token in Node.js:

$ npm install jsonwebtoken

const jwt = require('jsonwebtoken');

const publicKey = require('fs').readFileSync(__dirname + '/public-key.pem');
try {
  const verified = jwt.verify(tokenValue, publicKey, {algorithm: 'RS256'});
  console.log('verified');
} catch (e) {
  console.log('invalid token', e.message);
}   

Validating the token in Python:

$ pip install pyjwt
$ pip install pyjwt[crypto]

import jwt

with open('public-key.pem', 'r') as file:
    key = file.read()
    claims = jwt.decode(token, key, algorithms=['RS256'])
    print(claims)

JSON Web Key Set (JWKS)

The authentication token public key is also available as a JSON Web Key Set (JWKS) along with the public key for the institution’s Primo token (as an alternative to the Primo Public Key API). The JWKS can be accessed with the following URL:

https://api-{REGION}.hosted.exlibrisgroup.com/auth/{INST_CODE}/jwks.json

For example, this is the link for the JWKS for our test integration environment. The JWKS also supports a env query-string parameter which can be set to sandbox to retrieve the Primo key for the sandbox environment.

The example below uses the jsonwebtoken package along with the jwk-to-pem package to validate a token in Node.js.

const jwt = require('jsonwebtoken');
const jwkToPem = require('jwk-to-pem');
const got = require('got');

const getPublicKey = (header, callback) => {
  got(`https://api-na.hosted.exlibrisgroup.com/auth/${inst_code}/jwks.json`).json()
  .then(response => {
    let key = response.keys.find(k=>header.kid==k.kid);
    if (!key) throw new Error(`Cannot find key for kid ${kid}`);
    return callback(null, jwkToPem(key));
  })
  .catch(e=>{
    console.error('Error retrieving public key', e.message);
    return callback(e, null);
  })
}

jwt.verify(token, getPublicKey, (err, token) => {
  if (err) return console.error(err.message);
  console.log(token);
})