@villedemontreal/jwt-validator

Module to validate JWT generated by Kong

Availabililty

https://bitbucket.org/villemontreal/core-jwt-validator-nodejs-lib

Installation

    npm install --save @villedemontreal/jwt-validator
    yarn add @villedemontreal/jwt-validator

Usage

Initialisation

Un code utilisant cette librarie doit premièrement la configurer en appellant la fonction "ìnit(...)" exportée par le fichier "src/config/init.ts".

import { init as initJwtValidationLib } from '@villedemontreal/jwt-validator';
import { createLogger } from './utils/logger';
import { correlationIdService, init as initCidUtils } from '@villedemontreal/correlation-id';

// ...

export async function initComponents() {
  initJwtValidationLib(
    createLogger,
    () => {
      return correlationIdService.getId();
    },
    configs.security.jwt.host, // Optional: already defined
    configs.security.jwt.endPoint // Optional: already defined
  );

  //...
}

Notez qu'une fonction "isInited()" est exportée et permet au code appelant de valider que la librairie a été configurée correctement!

JWT Validation With Middleware

Route definition:

import { jwtValidationMiddleware } from '@villedemontreal/jwt-validator';

export function getAPIRoutes(): IHandlerRoute[] {
  return [
    // Get Account Information
    {
      method: HttpMethods.GET,
      path: '/v1/accounts/:id',
      handler: accountsController.getAccount,
      middlewares: [jwtValidationMiddleware()]
    }
  ];
}

Global definition in app.ts:

export async function createApp(apiRoutes: IHandlerRoute[]): Promise<express.Express> {
  // ...

  if (configs.security.jwt.enable) {
    let jwtMiddleware = jwtValidationMiddleware();
    app.use(function(req: express.Request, res: express.Response, next: express.NextFunction) {
      if (req && req.path && req.path.toLowerCase().startsWith(constants.EnpointTypeRoots.API)) {
        jwtMiddleware(req, res, next);
      } else {
        next();
      }
    });
  }

  // ...
}

User validation

Then in the controller, it's possible to check the ID inside the JWT:

import { UserValidator } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get inum from request
    let inum: string = req.params.id;

    let userValidator: UserValidator = new UserValidator(req);

    // Return if the ID is the same or not
    let same: boolean = userValidator.isUser(inum);

    // Throw an exception if the ID is not the same
    userValidator.verifyUser(inum);
}

Get JWT content

To get the JWT content, you have to cast the req variable with the custom type Request .

import { IJWTPayload, IRequestWithJwt } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get JWT content
    let jwtPayload: IJWTPayload = (<IRequestWithJwt>req).jwt;
}

Manual JWT Validation

Validate a JWT and a JWT and the ID inside the JWT

import { jwtValidator, IJWTPayload } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get inum from request
    let inum: string = req.params.id;

    // Validate Authorization header, check inum in JWT and get JWT content
    let jwtPayload: IJWTPayload = await jwtValidator.verifyAuthorizationHeader(req.header('Authorization'));

    // Check the ID inside the JWT
    assert.strictEqual(jwtPayload.sub, inum);
}

It is also possible to check to validate directly the JWT value:

import { jwtValidator, IJWTPayload } from '@villedemontreal/jwt-validator';

let jwt: string = '...';

// Validate JWT and get JWT content
let jwtPayload: IJWTPayload = await jwtValidator.verifyToken(jwt);

Token transformation middleware

When working locally, you do not have all the infrastructure required to simulate the translation between an access token and a JWT (ex: Kong).

Prior to usage of the jwtValidationMiddleware, you can use the token transformation middleware which do an API call to exchange your access token for an extended jwt and update the authorization header.

export async function createApp(apiRoutes: IHandlerRoute[]): Promise<express.Express> {
  // ...

  if (configs.security.jwt.enable) {
    if (configs.environment.isLocal) {
      // Required prior to the jwtValidationMiddleware
      app.use(tokenTransformationMiddleware(config));
    }

    // ...
    app.use(jwtValidationMiddleware())
  }

  // ...
}

Usage For Tests

This library provides a mock tool to generate your own JWT with a signature which it will be correcly validated.

There are two parts to do this:

• The method mockPublicKeys, clean the public keys cache and intercept the first request to get the public keys. Then, our mock keys are inserted in the pubic keys cache.

• The method generateJwt allows to produce your own JWT signed with a private key.

Example of tests with mocha:

import { jwtMock } from '@villedemontreal/jwt-validator';

describe('Test', function() {
  before(async function() {
    // Mock the public keys
    await jwtMock.mockPublicKeys();

    // Generate JWT
    let jwtToken = jwtMock.generateJwt();

    // Generate a JWT with your custom value:
    let jwtToken = jwtMock.generateJwt({
      accessToken: 'c9ba5a95-d7f9-41f9-9a24-a7e41882f7ef',
      iss: 'jwt-mock',

      // From Introspect
      exp: Date.now() + 3600,
      iat: Date.now(),
      // Use this keyId to have a valid public key
      keyId: 5,
      /*
                Key ID:
                - 1: Public Key expired with the status as "expired"
                - 2: Public Key expired WITHOUT the status as "expired"
                - 3: Public Key revoked
                - 4: Public Key still active but an expiration date is set
                - 5: Public Key active without an expiration date
            */

      // From ClientInfo
      displayName: 'Service Account',
      aud: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0008!2212.0010',

      // From UserInfo
      name: 'Guillaume Smaha',
      sub: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0000!0000.0001',
      inum: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0000!0000.0001',
      userName: '[email protected]',
      givenName: 'Guillaume',
      familyName: 'Smaha',

      customData: {
        // Role, permission, ...
      }
    });
  });

  it('should accept JWT and update password user', async function() {
    let payload: any = {
      oldPassword: 'testTest2',
      password: 'testTest3'
    };

    let response = await request(testApp)
      .put(`/api${configs.api.domainPath}/v1/accounts/${userInum}`)
      .set('Authorization', 'Bearer ' + jwtToken)
      .send(payload);

    assert.strictEqual(response.status, 200);
  });
});

Builder le projet

Note: Sur Linux/Mac assurz-vous que le fichier run est exécutable. Autrement, lancez chmod +x ./run.

Pour lancer le build :

• run compile ou ./run compile (sur Linux/Mac)

Pour lancer les tests :

• run test ou ./run test (sur Linux/Mac)

Mode Watch

Lors du développement, il est possible de lancer run watch (ou ./run watch sur Linux/mac) dans un terminal externe pour démarrer la compilation incrémentale. Il est alors possible de lancer certaines launch configuration comme Debug current tests file - fast dans VsCode et ainsi déboguer le fichier de tests présentement ouvert sans avoir à (re)compiler au préalable (la compilation incrémentale s'en sera chargé).

Notez que, par défaut, des notifications desktop sont activées pour indiquer visuellement si la compilation incrémentale est un succès ou si une erreur a été trouvée. Vous pouvez désactiver ces notifications en utilisant run watch --dn (disable notifications).

Déboguer le projet

Trois "launch configurations" sont founies pour déboguer le projet dans VSCode :

• "Debug all tests", la launch configuration par défaut. Lance les tests en mode debug. Vous pouvez mettre des breakpoints et ils seront respectés.

• "Debug a test file". Lance un fichier de tests en mode debug. Vous pouvez mettre des breakpoints et ils seront respectés. Pour changer le fichier de tests à être exécuté, vous devez modifier la ligne appropriée dans le fichier ".vscode/launch.json".

• "Debug current tests file". Lance le fichier de tests présentement ouvert dans VSCode en mode debug. Effectue la compîlation au préalable.

• "Debug current tests file - fast". Lance le fichier de tests présentement ouvert dans VSCode en mode debug. Aucune compilation n'est effectuée au préalable. Cette launch configuration doit être utilisée lorsque la compilation incrémentale roule (voir la section "Mode Watch" plus haut)

Test et publication de la librairie sur Nexus

En mergant une pull request dans la branche develop, un artifact "-pre.build" sera créé automatiquement dans Nexus. Vous pouvez utiliser cette version temporaire de la librairie pour bien la tester dans un réel projet.

Une fois mergée dans master, la librairie est définitiement publiée dans Nexus, en utilisant la version spécifiée dans le package.json.

Artifact Nexus privé, lors du développement

Lors du développement d'une nouvelle fonctionnalité, sur une branche feature, il peut parfois être utile de déployer une version temporaire de la librairie dans Nexus. Ceci permet de bien tester l'utilisation de la librairie modifiée dans un vrai projet, ou même dans une autre librairie elle-même par la suite utilisée dans un vrai projet.

Si le code à tester est terminé et prêt à être mis en commun avec d'autres développeurs, la solution de base, comme spécifiée à la section précédante, est de merger sur develop: ceci créera automatiquement un artifact "-pre-build" dans Nexus. Cependant, si le code est encore en développement et vous désirez éviter de polluer la branche commune develop avec du code temporaire, il y a une solution permettant de générer un artifact "[votre prénom]-pre-build" temporaire dans Nexus, à partir d'une branche feature directement:

1. Checkoutez votre branche feature dans une branche nommée "nexus". Ce nom est important et correspond à une entrée dans le Jenkinsfile.
2. Une fois sur la branche nexus, ajoutez un suffixe "-[votre prénom]" à la version dans le package.json, par exemple: "5.15.0-roger". Ceci permet d'éviter tout conflit dans Nexus et exprime clairement qu'il s'agit d'une version temporaire pour votre développement privé.
3. Commitez et poussez la branche nexus.
4. Une fois le build Jenkins terminé, un artifact pour votre version aura été déployé dans Nexus. Détruire votre branche dans Bitbucket pour permettre aux autres developpeurs d'utiliser cette approche.

Notez que, lors du développement dans une branche feature, l'utilisation d'un simple npm link local peut souvent être suffisant! Mais cette solution a ses limites, par exemple si vous désirez tester la librairie modifiée dans un container Docker.

Aide / Contributions

Pour obtenir de l'aide avec cette librairie, vous pouvez poster sur la salle Google Chat dev-discussions.

Notez que les contributions sous forme de pull requests sont bienvenues.