jwt-psk v1.0.2

Pre-shared JWT key authentication

A simple library that allows authentication by JWT signed with pre-shared key.

Synopsis

Library is intended to be used in an environment where several services are sending requests to one another. This requests are performed by services themselves or on behalf of some other entity.

Each service that make requests is assumed to be identified by name and to have an unique secret key. Each endpoint requests are send to is assumed to also have some name.

This library is used to issue and verify Json Web Tokens to authenticate services.

Token issuer specifies claims to identify itself, endpoint this token is intended for, and, optionally, subject the token is issued on behalf of. Standard JWT claims iss, aud and sub are used for that purpose. Payload is then signed by issuer's secret key.

To verify the token, endpoint finds a pre-shared key for the issuer specified in an iss claim, and checks the signature. aud claim is checked to match the endpoint name. Request is then processed as if it was made by entity specified in sub claim or in iss claim, if no sub is present.

Pre-shared keys are stored per issuer and algorithm, allowing issuer to sign tokens using different keys and algorithms

Usage

Library provides general purpose classes for usage with any applications and specific classes to use with Nest.js framework

General purpose classes

Following snippet shows how to use this library as express middleware framework to verify authentication tokens

import { AuthServiceBase, readToken } from "jwt-psk";
import express from "express";

const audience = [ "this.server.name", "alt.server.name" ];
const authConfig = {
  "doge-the-jwt-issuer": {
     "HS256": "WOW!such_Secret"
  }
};
const app = express();
const authService = new AuthServiceBase(authConfig, audience);

app.use((req, res, next) => {
  try { 
    authService.authenticate(readToken(req.headers.authorization));
  } catch (e) {
    res.return(403);
    return;
  }
  next();
});

To issue token, compatible with that server code:

import { createPSKToken } from "jwt-psk";

fetch("https://example.com/service", {
  headers: {
    "Authorization": `Bearer ${createPSKToken("doge-the-jwt-issuer", "WOW!such_Secret", "example.com")}`
  }
}).then(resp => processResponse(resp));

Nest server

Library provides middleware to assert that incoming request has proper auth header with JWT token signed by the key that belongs to on of known issuers, and audience claim matches one that is required by this server.

The following snippet shows configuration with static values.

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AuthModule, PSKAuthMiddleware } from "jwt-psk/nest";

@Module({
  import: [
    AuthModule.configure({
      audience: [ "this.server.name", "alt.server.name" ],
      authConfig: {
        "doge-the-jwt-issuer": {
           "HS256": "WOW!such_Secret"
        }
      }
    })
  ]
})
export class AppModule implements NestModule  {
  configure(consumer: MiddlewareConsumer): void {
    consumer
      .apply(PSKAuthMiddleware)
      .forRoutes("*");
  }
}

The following snippet shows configuration with values obtained from configuration

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AuthModule, PSKAuthMiddleware } from "jwt-psk/nest";
import { ConfigModule, ConfigService } from "./config";

@Module({
  import: [
    AuthModule.configureAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        audience: config.serviceGlobalAudience,
        authConfig: config.preSharedKeys
      })
    })
  ]
})
export class AppModule implements NestModule  {
  configure(consumer: MiddlewareConsumer): void {
    consumer
      .apply(PSKAuthMiddleware)
      .forRoutes("*");
  }
}