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 URLJWT_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.