Implémentation de l’API en Node.js (applications mobiles + API)

L’implémentation en Node.js de l’API pour le scénario d’architecture Mobile + API

Ce document fait partie du scénario d’architecture Mobile + API et explique comment mettre en œuvre l’API en Node.js. Le code source complet de l’implémentation de l’API Node.js se trouve dans ce dépôt GitHub.

Veuillez consulter le scénario pour en savoir plus sur la solution mise en œuvre.

1 Définir les points de terminaison de l’API

Cette implémentation utilise le cadriciel d’application Web Express pour créer une 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 configure votre fichier package.json.

Conservez les paramètres par défaut ou modifiez-les selon vos besoins.

Le fichier package.json de notre exemple ressemble à ceci :

{
  "name": "timesheets-api",
  "version": "1.0.0",
  "description": "API used to add timesheet entries for employees and contractors",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "dependencies": {
    "body-parser": "^1.20.0",
    "cors": "^2.8.5",
    "express": "^4.18.0",
    "express-oauth2-jwt-bearer": "^1.6.0"
  },
  "author": "Auth0",
  "license": "MIT"
}

Installer les dépendances

Ensuite, configurez les dépendances avec les modules suivants :

• express : Ce module ajoute le framework Web Express.
• cors : Ce module ajoute la prise en charge de l’activation de CORS, ce qui est nécessaire puisque l’API est appelée à partir d’une application monopage qui s’exécute 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 (jeu de clés Web JSON). À l’aide de expressJwtSecret, nous pouvons générer un fournisseur de secret qui transmet la clé de signature appropriée à 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 authentifie 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 dépôt GitHub express-jwt.
• body-parser : Il s’agit d’un intergiciel Node.js d’analyse du corps des requêtes. 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 à exploiter.

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 :

• Récupérer les dépendances.
• Implémenter le ou les points de terminaison.
• Démarrer le serveur API.

Voici notre exemple d’implémentation :

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 à l’aide de node server, puis 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 l’appeler. Passez à l’étape suivante pour voir comment résoudre ce problème.

2 Sécuriser les points de terminaison de l’API

Pour valider notre jeton, utilisez la fonction jwt, fournie par le middleware express-jwt, ainsi que jwks-rsa pour récupérer notre secret. Les bibliothèques font ce qui suit :

1. express-jwt décode le jeton et transmet la requête, l’en-tête et la charge utile à jwksRsa.expressJwtSecret.
2. jwks-rsa télécharge toutes les clés de signature depuis le point de terminaison JWKS et vérifie si l’une d’elles correspond au kid dans l’en-tête du JWT. Si aucune clé de signature ne correspond au kid reçu, une erreur est générée. S’il y a correspondance, la bonne clé de signature est transmise à express-jwt.
3. express-jwt poursuit ensuite sa logique pour valider la signature du jeton, son expiration, l’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 exemple d’implémentation (une partie du code est omise par souci de concision) :

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

Pour tester également 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 est la valeur du jeton récupéré à la première étape).

3 Vérifiez les autorisations de l’application

Dans cette étape, nous ajoutons la possibilité de vérifier si l’application dispose des autorisations (ou scopes) nécessaires et d’utiliser notre point de terminaison pour créer une feuille de temps. Plus précisément, nous voulons nous assurer que le jeton possède le scope approprié, soit batch:upload.

Pour ce faire, nous utilisons le package Node.js express-jwt-authz ; ajoutez-le donc à votre projet :

npm install express-jwt-authz --save

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

Nous ajoutons 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 dispose des autorisations appropriées pour appeler le point de terminaison visé. Pour en savoir plus, consultez le dépôt GitHub d’express-jwt-authz.

Voici notre exemple d’implémentation (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 la requête - code omis

// créer le point de terminaison 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 jeton qui n’inclut pas ce scope, nous devrions obtenir le message d’erreur Forbidden avec le code d’état HTTP 403. Vous pouvez le vérifier en supprimant ce scope de votre API.

4 Déterminer l’identité de l’utilisateur

Le middleware express-jwt utilisé pour valider le JWT renseigne également req.user avec l’information contenue dans le JWT. Si vous souhaitez utiliser la revendication sub pour identifier l’utilisateur de manière unique, vous pouvez utiliser req.user.sub. Pour l’application de feuilles de temps, nous voulons utiliser l’adresse courriel de l’utilisateur comme identifiant unique.

Créer une Action

D’abord, créez une nouvelle Action qui ajoutera l’adresse courriel de l’utilisateur au jeton d’accès.

1. Accédez à Auth0 Dashboard > Actions > Library, puis sélectionnez Build Custom.

2. Saisissez un Nom descriptif pour votre Action (par exemple, Add email to access token), sélectionnez le déclencheur Login / Post Login, puis sélectionnez Create.

3. Repérez l’éditeur de code Actions, copiez-y le code JavaScript suivant, puis sélectionnez Save Draft pour enregistrer vos modifications :

   exports.onExecutePostLogin = async (event, api) => {
     const namespace = 'https://my-app.example.com';
     api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
   }
   
   Le namespace sert à garantir que la revendication a un nom unique qui n’entre pas en conflit avec les revendications OIDC standard ni avec les services internes. Pour en savoir plus sur les restrictions et les directives relatives aux revendications avec et sans espace de noms, consultez Create Custom Claims.

4. Dans la barre latérale de l’éditeur de code Actions, sélectionnez Test (icône de lecture), puis sélectionnez Run pour tester votre code.

5. Lorsque vous êtes prêt à déployer l’Action, sélectionnez Deploy.

Ajouter votre Action au déclencheur Post-Login

Ensuite, ajoutez l’Action que vous avez créée au déclencheur Post-Login. Pour savoir comment attacher des Actions à des déclencheurs, consultez Write Your First Action.

Récupérer l’identifiant unique

Enfin, dans votre API, récupérez la valeur de la revendication à partir de req.auth. Utilisez cette valeur comme identifiant 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);
});