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

La mise en œuvre de l’API en Node.js pour le scénario d’architecture applications mobiles + 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 cette mise en œuvre de l’API en 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éfinissez les points de terminaison de l’API

Cette mise en œuvre utilise le framework d’applications web Express pour créer une API Node.js.

Créez un fichier package.json

Créez un dossier pour votre API, accédez-y, puis exécutez npm init. Cela crée 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 d’applications Web Express.
• cors : Ce module ajoute la prise en charge 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 des clés de signature RSA à partir d’un endpoint JWKS (JSON Web Key Set). En utilisant expressJwtSecret, nous pouvons générer un fournisseur de secret qui fournit 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 plus d’informations, consultez le dépôt GitHub express-jwt.
• body-parser : Il s’agit d’un middleware Node.js d’analyse du corps de la requête. 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 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.
• Lancer le serveur d’API.

Voici un 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 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 avec le message This is the POST /timesheets endpoint.

Nous avons maintenant notre endpoint, mais n’importe qui peut lui envoyer une requête. Passez à l’étape suivante pour voir comment remédier à cela.

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

Afin de valider notre jeton, utilisez 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é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 JWKS endpoint 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 entrant, une erreur sera générée. En cas de correspondance, la bonne clé de signature est transmise à express-jwt.
3. express-jwt poursuit ensuite sa propre logique 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 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 de mise en œuvre (une partie du code est omise par souci de brièveté) :

Si nous démarrons notre serveur maintenant et effectuons un 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).

Afin de tester aussi le scénario fonctionnel, nous devons :

• Obtenir un jeton d’accès. Pour savoir comment procéder, 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 que nous avons récupéré à la première étape).

3 Vérifiez les autorisations de l’application

À cette étape, nous ajoutons la possibilité de vérifier si l’application dispose des autorisations (ou des scopes) 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 contient 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 particulier afin d’exécuter un point de terminaison donné.

Nous ajoutons une dépendance supplémentaire. La bibliothèque express-jwt-authz, qui est utilisée conjointement avec express-jwt, valide le JWT et s’assure qu’il comporte les permissions appropriées pour faire une requête au 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 brièveté) :

// 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 la vérification du JWT - code omis

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

// créer le point de terminaison de l'API de 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);
})

// démarrer 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 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 définit aussi req.user à partir des informations contenues dans le JWT. Si vous souhaitez utiliser la revendication sub pour identifier l’utilisateur de manière unique, vous pouvez utiliser req.user.sub. Dans 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 Name descriptif pour votre Action (par exemple, Add email to access token), sélectionnez le trigger Login / Post Login, puis sélectionnez Create.

3. Repérez le Actions Code Editor, 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);
   }
   
   La valeur namespace sert à garantir que la revendication a un nom unique qui n’entre pas en conflit avec les revendications OIDC standard ni avec des services internes. Pour en savoir plus sur les restrictions et les lignes directrices relatives aux revendications avec espace de noms et sans espace de noms, consultez Create Custom Claims.

4. Dans la barre latérale du Actions Code Editor, 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 Trigger Post-Login

Ensuite, ajoutez l’Action que vous avez créée au Trigger Post-Login. Pour savoir comment associer des Actions à des Triggers, 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 la 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);
});