Applications serveur + API : mise en œuvre de l’API en Node.js

La mise en œuvre de l’API en Node.js pour le scénario d’architecture Applications serveur + API

Dans le cadre du scénario d’architecture serveur + API, nous allons mettre en œuvre la Timesheets API en Node.js. Veuillez consulter le scénario pour en savoir plus sur la solution mise en œuvre.

Le code source complet de la mise en œuvre de l’API en Node.js se trouve dans ce dépôt GitHub.

​

Étape 1. Définir le point de terminaison de l’API

Nous utiliserons le framework d’application Web Express pour créer notre API Node.js.

​

Créer un fichier package.json

Créez un dossier pour votre API, accédez-y, puis exécutez npm init. Cela créera votre fichier package.json.

Vous pouvez conserver les paramètres par défaut ou les modifier à votre guise.

Voici à quoi ressemble le fichier package.json de notre exemple :

{
  "name": "timesheets-api",
  "version": "1.0.0",
  "description": "API used to add timesheet entries for employees and contractors",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/auth0-samples/auth0-pnp-timesheets.git"
  },
  "author": "Auth0",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auth0-samples/auth0-pnp-timesheets/issues"
  },
  "homepage": "https://github.com/auth0-samples/auth0-pnp-timesheets#readme"
}

​

Installer les dépendances

Ensuite, nous devons configurer nos dépendances. Nous utiliserons les modules suivants :

• express : Ce module ajoute le framework d’applications web Express.
• jwks-rsa : Cette bibliothèque récupère les clés de signature RSA à partir d’un point de terminaison JWKS (JSON Web Key Set). En utilisant expressJwtSecret, nous pouvons générer un fournisseur de secret qui fournira la bonne clé de signature à express-jwt selon le kid dans le header du JWT. Pour en savoir plus, consultez le repository GitHub node-jwks-rsa.
• express-jwt : Ce module vous permet d’authentifier les requêtes HTTP à l’aide de jetons JWT dans vos applications Node.js. Il fournit plusieurs fonctions qui facilitent l’utilisation des JWT. Pour en savoir plus, consultez le repository GitHub express-jwt.
• body-parser : Il s’agit d’un middleware Node.js d’analyse du body. Il extrait l’intégralité du body d’un stream de request entrant et l’expose dans req.body sous une forme plus facile à utiliser. Pour plus d’information et pour découvrir plusieurs solutions de rechange, consultez le repository GitHub de body-parser.

Pour installer ces dépendances, exécutez ce qui suit :

npm install express express-jwt jwks-rsa body-parser --save

​

Implémentez le point de terminaison

Accédez au répertoire de votre API et créez un fichier server.js. Votre code doit :

• Définir les dépendances.
• Activer le middleware d’analyse du corps de la requête.
• Implémenter le point de terminaison.
• Démarrer le serveur API.

Voici un exemple de mise en œuvre :

// définir les dépendances
const express = require('express');
const app = express();
const jwt = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const bodyParser = require('body-parser');

// activer l'utilisation du middleware d'analyse du corps de la requête
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// créer le point de terminaison API de téléversement des feuilles de temps
app.post('/timesheets/upload', function(req, res){
  res.status(201).send({message: "This is the POST /timesheets/upload endpoint"});
})

// lancer le serveur API à localhost:8080
app.listen(8080);

Démarrez votre serveur API à l’aide de node server, puis faites une requête HTTP POST à localhost:8080/timesheets/upload. Vous devriez voir une réponse JSON contenant le message This is the POST /timesheets/upload endpoint.

Nous avons donc maintenant notre point de terminaison, mais n’importe qui peut y faire une requête. Passez au paragraphe suivant pour voir comment régler cela.

​

Étape 2. Sécuriser le point de terminaison de l’API

Pour valider notre jeton, nous utiliserons la fonction jwt, fournie par le middleware express-jwt, ainsi que le package jwks-rsa pour récupérer la clé publique depuis Auth0. Ces bibliothèques font ce qui suit :

1. express-jwt décodera le jeton et transmettra la requête, l’en-tête et la charge utile à jwksRsa.expressJwtSecret.
2. jwks-rsa téléchargera ensuite toutes les clés de signature depuis le point de terminaison JWKS et vérifiera si l’une d’elles correspond au kid dans l’en-tête du JWT. Si aucune des clés de signature ne correspond au kid reçu, une erreur sera générée. En cas de correspondance, nous transmettrons la bonne clé de signature à express-jwt.
3. express-jwt poursuivra ensuite son propre traitement pour valider la signature du jeton, l’expiration, audience et issuer.

Les étapes que nous suivrons dans notre code sont les suivantes :

• Créer la fonction middleware pour valider le jeton d’accès.
• Activer le middleware dans nos routes.

C’est aussi un bon moment pour mettre en œuvre la logique permettant d’enregistrer les entrées de feuille de temps dans une base de données locale, ou dans tout autre mécanisme de stockage que vous préférez. Voici notre exemple de mise en œuvre (une partie du code a été omise par souci de concision) :

Si nous lançons notre serveur maintenant et effectuons une requête HTTP POST vers localhost:8080/timesheets/upload, nous devrions obtenir le message d’erreur Missing or invalid token (ce qui est tout à fait normal puisque nous n’avons pas envoyé de jeton d’accès dans notre requête).

Pour tester aussi le scénario fonctionnel, nous devons :

• Obtenir un jeton d’accès. Pour savoir comment faire, consultez : Get an Access Token
• Appeler l’API en ajoutant un en-tête Authorization à notre requête avec la valeur Bearer ACCESS_TOKEN (où ACCESS_TOKEN correspond à la valeur du jeton récupéré à la première étape).

​

Étape 3. Vérifier les permissions du client

À cette étape, nous allons ajouter à notre mise en œuvre la possibilité de vérifier si le client a les permissions (ou scope) nécessaires pour utiliser notre point de terminaison afin de téléverser une feuille de temps. Plus précisément, nous voulons nous assurer que le jeton a le bon scope, soit batch:upload.

Pour ce faire, nous utiliserons le package Node.js express-jwt-authz, alors ajoutez-le à votre projet :

npm install express-jwt-authz --save

Maintenant, il suffit d’ajouter un appel à jwtAuthz(...) dans votre middleware pour vous assurer que le JWT contient une portée précise avant d’accéder à un point de terminaison donné. Voici notre exemple de mise en œuvre (une partie du code est omise par souci de concision) :

// définir les dépendances - une partie du code est omise
const jwtAuthz = require('express-jwt-authz');

// Créer le middleware pour la vérification du JWT

// Activer l'utilisation du middleware d'analyse du corps de la requête
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// Endpoint de téléversement par lot
app.post('/timesheets/upload', checkJwt, jwtAuthz(['batch:upload']), function(req, res){
  var timesheet = req.body;

  // Enregistrer l'entrée de feuille de temps dans la base de données...

  //envoyer la réponse
  res.status(201).send(timesheet);
});

// lancer le serveur API à localhost:8080 - code omis

Si nous appelons notre API avec un token qui n’inclut pas cette scope, nous devrions obtenir le message d’erreur Forbidden avec le code d’état HTTP 403. Vous pouvez le vérifier en retirant cette scope de votre API.

C’est tout ! Vous avez terminé !