@villedemontreal/jwt-validator
v5.10.3
Published
Module to validate JWT (JSON Web Tokens)
Downloads
1,059
Readme
@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
(d
isable n
otifications).
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:
- Checkoutez votre branche
feature
dans une branche nommée "nexus
". Ce nom est important et correspond à une entrée dans leJenkinsfile
. - Une fois sur la branche
nexus
, ajoutez un suffixe "-[votre prénom]
" à la version dans lepackage.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é. - Commitez et poussez la branche
nexus
. - 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.