Asymmetric JWT Signing using AWS KMS

TL;DR

Node.js implementation using asymmetric encryption key stored on AWS KMS to sign JWT tokens and verifying them using the public key. You can skip to the solution architecture.

JWT, Token Verification, and You

JWT tokens are an industry-standard, used mainly for user authentication.

It’s basically a JSON block with a signature attached, which allows you to verify that the content of the JSON was not tempered with. In the most common case, when your user logs in she gets a JWT token that is added to every request she sends, and this token is used to verify her identity.

How do you verify that your user is really who she claims to be? You take the signature from the JWT token and using your encryption key, you verify that it matches the content of the JSON. That’s called Token Verification. The process of the creation of the signature in the first place is called Signing.

In order to sign and verify the token, you need an encryption method - either a symmetric or asymmetric (also called Public-Key encryption). In symmetric encryption, you’ll use the same key to sign and verify your token. In asymmetric encryption, you’ll use your private key to sign the token, and the public key to verify it.

What are we trying to solve?

Given a private key (either a symmetric or asymmetric), signing and verifying a string is quite simple, and there are multiple libraries for that.

However, to use most of these libraries you’ll needs to have access to your secret key in order to sign the message (and, if you’re using symmetric encryption, also to validate it). This is where things start to get messy: you need to keep your secret key somewhere that is reachable by your code, and at the same time, you’ll need to add a lot of protection layers on it to make sure no one gets his hands on it.

So what we want to solve is this: How to minimize the access to your private key and still be able to use it without too much fuss.

The first part of the solution is to use asymmetric encryption. In asymmetric you only need the private key to sign the token. The validation phase only requires the public key, and that can be, well, publicly available. This split will minimize the number of functions that need to access the private key.

The second part of the solution is to use AWS’s KMS service, which allows you to generate keys and use the KMS API to sign/validate messages without ever having direct access to the private key. Yes, that’s right: you’re generating a new private key, but you never get the private key. All you can do is ask AWS to use your key in order to sign or validate a token.

Let’s see how to do that.

The Solution Architecture

Our Solution will be composed of 3 component:

1. A KMS-Stored RSA key
2. A Lambda function to sign our tokens
3. A piece of code we can use wherever we want that can validate that the token was indeed generated by us.

Things we’ll need for our POC:

1. RSA Key generated in AWS KMS
2. Public Key part of our RSA key
3. A Lambda function to do the encryption (with permissions to the KMS key)
4. A local function (either a Lambda or plain local function) to validate the token using the public key

Generating RSA Key on AWS KMS

In AWS console:

1. Go to KMS
2. Customer managed keys
3. Create Key:
   • Key type: Asymmetric
   • Key usage: Sign and verify
   • Key spec: RSA_2048 (You can pick the bigger keys, but OpenSSL recommends 2048

At the next page will ask you who gets permission to manage the key and to use it. Make sure you give yourself admin permissions on the key.

Getting the public keys

In AWS console:

1. Go to KMS
2. Customer managed keys.
3. Click on your key
4. Click “Public Key”
5. Click “Download”.

Save the key file as public.pem, we’ll use it in the next step.

The Signing Lambda

1. Create a new AWS Lambda, and make sure to give it permissions to the KMS key you’ve created.
2. Make sure to upload your node_modules with the base64url package installed.

const AWS = require("aws-sdk");
const kms = new AWS.KMS();
const util = require('util')

const base64url = require("base64url");
const keyId = '<YOUR_KEY_ID>'

async function sign(headers, payload, key_arn) {

    payload.iat = Math.floor(Date.now() / 1000);

    const tomorrow = new Date()
    tomorrow.setDate(tomorrow.getDate() + 1)
    payload.exp = Math.floor(tomorrow.getTime() / 1000);

    let token_components = {
        header: base64url(JSON.stringify(headers)),
        payload: base64url(JSON.stringify(payload)),
    };

    let message = Buffer.from(token_components.header + "." + token_components.payload)

    let res = await kms.sign({
        Message: message,
        KeyId: keyId,
        SigningAlgorithm: 'RSASSA_PKCS1_V1_5_SHA_256',
        MessageType: 'RAW'
    }).promise()

    token_components.signature = res.Signature.toString("base64")
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');

    return token_components.header + "." + token_components.payload + "." + token_components.signature;

}

let header = {
  "alg": "RS256",
  "typ": "JWT"
}

let payload = {
  "user_name": "yossale"
}

exports.handler = async (event) => {
    console.log("Start")
    let res = await sign(header, payload, keyId)
    console.log(`JWT token: [${res}]`)
}

The verification code

Since we used asymmetric encryption, all we need to verify our JWT token is the public key:

const jwt = require('jsonwebtoken');
const fs = require('fs')

function decode(token, pemFile) {
    let cert = fs.readFileSync(pemFile);  // get public key
    jwt.verify(token, cert, function (err, decoded) {
        if (err) {
            console.error("Error", err)
        }
        console.log(`${JSON.stringify(decoded)}`)
    });
}

let myToken = `<YOUR_TOKEN_HERE>`
let myPem = `public.pem`
decode(myToken, myPem)

You can also use JWT.io to verify that your token is valid: Enter your token, and add your private key at the bottom right. If everything is OK, you’ll see a If everything is OK, you’ll see a “Signature Verified” label.

Sum Up

Security is always hard, and one of the best ways of keeping secrets is to, well - not to know them in the first place. In this post, we showed how you can generate industry-standard authentication tokens while significantly reducing the risk of compromising your secret keys.