@digitalfactory/railauth-helper

This package helps node applications with verifying access tokens provided by the RailAuth Service.

Usage no npm install needed!

<script type="module">
  import digitalfactoryRailauthHelper from 'https://cdn.skypack.dev/@digitalfactory/railauth-helper';
</script>

README

RailAuth Helper

This package helps node applications with verifying access tokens provided by the RailAuth Service.

Install

$ npm install @digitalfactory/railauth-helper

Environment Variables

To use this package it's advised that you have the following in your environment variable files:

  • HOSTNAME_URL: The URL of your project's node app AKA resource server URL
  • JWT_PUBLIC_KEY: RailAuth's JWT Public Key

Hostname URL

The value of the hostname URL should exactly match the value of the Resource Server URL for your Client application as setup in the RailAuth Portal.

To add the hostname URL to your .env(.dev/.ppte/.prod) file you can do something like the following (e.g. for DEV environment):

HOSTNAME_URL=OCP_SVC:project-name-dev/project-name-node-app

RailAuth Service Public Key

You will need to specify the correct RailAuth Service public key in order to be able to verify access tokens.

Add the following to your .env(.dev/.ppte/.prod) file (replacing the -dev at the end with -ppte or -prod depending on the .env file you're updating):

JWT_PUBLIC_KEY=OCP_SECRET:rail-auth-service-jwt-public-key-dev

For local development, if your front-end application is connecting to the DEV RailAuth Service, then you can add the following into your local .env file:

JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA96DEifw9JTy3yFBaCLNF\n7kPpx8a9KHwIjrulj8XIFdFshWBQZ1Wi0SFj1Bjr1uRRNa1WFOHYNKgTB4aQPln7\n0Yk1gHLUpLUORpFB7Cd26VJoGoZ0PsMa+3BugV8xUhnn7O1JReMUk8dlPBrD9Zuk\nRBLMOExM6ZrZvo+EmLlSALASgKw5ljVAC3+5OpAXFvXdzAZd/fyxcjNS3F/g2OSd\nAYcGePBSJUn4VCWGe1WT72G2VK3vjyK7H3jLIoPqZgwT87I8ZaPjevEOPHFqUSMo\nTCX0ZTkd0zGxm6GEXrfV44KUuH1Ho8yhvWrOjQzjnOoYGNXTUSIfRQl+SJNNfZIg\nMwIDAQAB\n-----END PUBLIC KEY-----

Usage

Firstly, import the RailAuthHelper as follows:

import RailAuthHelper from "@digitalfactory/railauth-helper";

then create a new instance of the RailAuthHelper:

const railauthhelper = new RailAuthHelper({
    hostnameUrl: process.env.HOSTNAME_URL || "http://localhost:8001",
    publicKey: process.env.JWT_PUBLIC_KEY as string
});

you can then verify any RailAuth access tokens:

try {
    const decodedToken = railauthhelper.verifyAccessToken("<your-access-token>");
} catch (e) {
    // handle any errors here
}

if you would like to verify that the user is in at least one of a given list of groups then you can do:

try {
    const decodedToken = railauthhelper.verifyAccessToken(
        "<your-access-token>", 
        ["RailAuth-R-NetworkRail-Users"]
    );
} catch (e) {
    // handle any errors here
}

Errors & Codes

An error may be thrown during verification if there is a problem -

Wrong type of token (i.e. not an access token)

This error means the token you've tried to verify is not an access token.

Error object:

  • message: 'Invalid token: header.typ mismatch'

Not a member of group

If you have specified a list of groups for the verifyAccessToken function, then the following error will be thrown if the user is not in at least one of those groups.

Error object:

  • message: 'Invalid token: user not in group'

Other errors

Please see here for a list of other possible errors.