Mise en œuvre de l’API en Node.js (SPAs + API)

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

​

Mise en œuvre de l’API en Node.js (SPAs + API)

Ce document fait partie du scénario d’architecture SPA + API et explique comment mettre en œuvre l’API en Node.js. Consultez 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 les points de terminaison de l’API

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

​

Créer un fichier package.json

Créez un dossier pour votre API, placez-vous dedans et exécutez npm init. Cette commande créera votre fichier package.json.

Vous pouvez conserver les paramètres par défaut ou les modifier comme bon vous semble.

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’application web Express.
• cors : Ce module ajoute la prise en charge de CORS, ce qui est nécessaire puisque l’API sera appelée à partir d’une Single-Page Application exécutée sur un domaine différent dans un navigateur web.
• 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 en fonction du kid dans l’en-tête JWT. Pour en savoir plus, consultez le dépôt GitHub node-jwks-rsa.
• express-jwt : Ce module vous permet d’authentifier des 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 dépôt GitHub express-jwt.
• body-parser : Il s’agit d’un middleware d’analyse du corps pour Node.js. Il extrait l’intégralité du corps d’un flux de requête entrant et l’expose dans req.body sous une forme plus facile à utiliser. Pour en savoir plus et découvrir plusieurs solutions de rechange, consultez le dépôt GitHub body-parser.

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

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

​

Implémentez les points de terminaison

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

• Installer les dépendances.
• Implémenter le ou les points de terminaison.
• Démarrer le serveur d’API.

Voici notre exemple de mise en œuvre :

const express = require('express');
const app = express();
const { expressjwt: jwt } = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const cors = require('cors');
const bodyParser = require('body-parser');

// Activer CORS
app.use(cors());

// 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 de l'API des feuilles de temps
app.post('/timesheets', function(req, res){
  res.status(201).send({message: "This is the POST /timesheets endpoint"});
})

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

Démarrez votre serveur d’API avec node server et envoyez une requête HTTP POST à localhost:8080/timesheets. Vous devriez voir une réponse JSON contenant le message This is the POST /timesheets endpoint.

Nous avons maintenant notre point de terminaison, mais n’importe qui peut lui envoyer une requête. Passez au paragraphe suivant pour voir comment nous pouvons corriger cela.

​

Étape 2. Sécuriser les points de terminaison de l’API

Pour valider notre jeton, nous utiliserons la fonction jwt, fournie par le middleware express-jwt, ainsi que jwks-rsa pour récupérer notre secret. 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 à partir du 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 entrant, une erreur sera générée. S’il y a correspondance, nous transmettrons la bonne clé de signature à express-jwt.
3. express-jwt poursuivra ensuite sa propre logique pour valider la signature du jeton, l’expiration, audience et l’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 l’utilisation du middleware dans nos routes.

Vous pouvez aussi écrire du code pour enregistrer réellement la feuille de temps dans une base de données. Voici notre mise en œuvre d’exemple (une partie du code est omise par souci de concision) :

Si nous démarrons notre serveur maintenant et envoyons une requête HTTP POST à localhost:8080/timesheets, 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 où tout fonctionne, nous devons :

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

​

Étape 3. Vérifier les permissions de l’application

Dans cette étape, nous ajouterons à notre mise en œuvre la possibilité de vérifier si l’application dispose des permissions (ou de la portée scope) nécessaires pour utiliser notre point de terminaison afin de créer une feuille de temps. Plus précisément, nous voulons nous assurer que le token comporte la bonne portée, 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

Il suffit maintenant d’ajouter un appel à jwtAuthz(...) à votre middleware pour vous assurer que le JWT contient un scope précis afin d’exécuter un point de terminaison donné.

Nous allons ajouter une dépendance supplémentaire. La bibliothèque express-jwt-authz, utilisée conjointement avec express-jwt, valide le JWT et s’assure qu’il comporte les permissions appropriées pour effectuer une requête vers le point de terminaison voulu. Pour en savoir plus, consultez le dépôt GitHub express-jwt-authz.

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');

// Activer CORS - code omis

// Créer le middleware pour vérifier le JWT - code omis

// Activer l'utilisation du middleware d'analyse du corps de requête - code omis

// créer le point de terminaison de l'API des feuilles de temps
app.post('/timesheets', checkJwt, jwtAuthz(['create:timesheets'], { customUserKey: 'auth' }), function(req, res){
  var timesheet = req.body;

  // Enregistrer la 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 ce scope, nous devrions obtenir le message d’erreur Forbidden avec le code d’état HTTP 403. Vous pouvez le tester en supprimant ce scope de votre API.

​

Étape 4. Déterminer l’identité de l’utilisateur

Le middleware express-jwt, utilisé pour valider le JWT, renseigne aussi req.auth avec les informations contenues dans le JWT. Si vous souhaitez utiliser la claim sub pour identifier l’utilisateur de façon unique, vous pouvez simplement utiliser req.auth.sub.

Dans le cas de l’application de feuilles de temps, toutefois, nous voulons utiliser l’adresse courriel de l’utilisateur comme identificateur unique.

La première chose à faire est donc d’écrire une règle qui ajoutera l’adresse courriel de l’utilisateur au jeton d’accès. Allez à la section Rules du Dashboard et cliquez sur le bouton Create Rule.

Vous pouvez donner à la règle un nom descriptif, par exemple Add email to Access Token, puis utiliser le code suivant pour la règle :

function (user, context, callback) {
  const namespace = 'https://api.exampleco.com/';
  context.accessToken[namespace + 'email'] = user.email;
  callback(null, user, context);
}

Le namespace sert à garantir que le claim porte un nom unique et qu’il n’entre pas en conflit avec les noms des claims OIDC standard. Toutefois, Auth0 prend en charge les claims personnalisés avec et sans espace de noms. Pour en savoir plus sur les claims personnalisés, consultez Create Custom Claims.

Ensuite, dans votre API, vous pouvez récupérer la valeur du claim à partir de req.auth et l’utiliser comme identité utilisateur unique à associer aux entrées de feuille de temps.

app.get('/timesheets', checkJwt, jwtAuthz(['read:timesheets'], { customUserKey: 'auth' }), function(req, res) {
  var timesheet = req.body;

  // Associer l'entrée de feuille de temps à l'utilisateur actuel
  var userId = req.auth['https://api.exampleco.com/email'];
  timesheet.user_id = userId;

  // Enregistrer la feuille de temps dans la base de données...

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