Drupal 10 : Authentification OAuth 2.0 pour sécuriser JSON:API avec les modules Consumers et Simple OAuth

｜

Mise à jour le 14 Sep 2024

Introduction

Dans un environnement où les API jouent un rôle central dans l’intégration d’applications, il est essentiel de garantir leur configuration correcte et sécurisée. Cet article explique comment mettre en place et sécuriser une API dans Drupal 10 en utilisant les modules JSON:API, JSON Extras, Simple OAuth, et Consumers. Vous apprendrez à configurer une API sécurisée pour les utilisateurs avec des permissions spécifiques, permettant un accès contrôlé aux données exposées via JSON.

Prérequis

Avant de commencer la configuration, vous devez disposer d’un environnement Drupal fonctionnel. Pour des instructions détaillées sur l’installation de Drupal, veuillez vous référer à Comment installer Drupal dans un conteneur docker

Use case

Nous mettrons en œuvre la fonctionnalité de sécurisation d’une API pour les utilisateurs ayant le rôle “OAUTH_ROLE“. D’abord, ce rôle sera créé avec les permissions nécessaires. Les modules Consumers et Simple OAuth sont essentiels pour mettre en place un système d’authentification OAuth sécurisé dans Drupal. Simple OAuth gère l’émission des jetons d’accès pour authentifier les utilisateurs, tandis que Consumers permet de restreindre l’accès à l’API en fonction des permissions définies. Cette combinaison offre une solution robuste pour sécuriser les échanges de données, garantissant que seuls les utilisateurs autorisés peuvent accéder aux endpoints JSON de l’API. Après avoir généré un token OAuth pour un utilisateur “OAUTH_ROLE“, nous testerons l’accès aux endpoints JSON sécurisés, en confirmant que seuls les utilisateurs avec le bon token peuvent accéder aux données.

Installation et activation des modules nécessaires

Pour commencer la configuration de votre API sécurisée, la première étape est d’installer et d’activer les modules indispensables.

JSON:API : Permet d’exposer les entités Drupal via une API RESTful.
JSON:API Extras : Fournit des configurations supplémentaires pour JSON.
JSON:API Permission Access : Ajoute un contrôle d’accès aux routes JSON, simplifiant la gestion des permissions sans configuration manuelle pour chaque entité ou champ.
Simple OAuth : Fournit une méthode d’authentification OAuth 2.0 pour les API RESTful.
Consumers : Permet de configurer des permissions spécifiques pour les applications consommant l’API, en contrôlant quels utilisateurs ou rôles peuvent accéder aux différentes routes de l’API.

Vous pouvez installer ces modules en utilisant Composer, qui est l’outil de gestion des dépendances pour PHP, permettant de télécharger et de gérer les modules Drupal et leurs dépendances. Voici les commandes Composer pour installer les modules nécessaires :

composer require 'drupal/jsonapi_extras:^3.24'
composer require 'drupal/jsonapi_permission_access:^1.0'
composer require 'drupal/simple_oauth:^5.2'
composer require 'drupal/consumers:^1.19'

Étant donné que JSON:API fait partie du noyau (depuis la version 8.7.x), vous n’avez pas besoin de l’installer mais juste de l’activer.

Vous pouvez activer ces modules soit directement depuis l’interface d’administration de Drupal sous Extend, soit en utilisant la ligne de commande Drush avec la commande suivante

drush en jsonapi jsonapi_extras simple_oauth consumers -y

Configuration de JSON:API et JSON:API Extras

Pour configurer JSON:API, accédez à /admin/config/services/jsonapi pour spécifier si chaque endpoint doit être en lecture seule ou autoriser toutes les opérations CRUD (Create, Read, Update, Delete)

Ensuite, accédez à la page de configuration de JSON:API Extras à l’adresse /admin/config/services/jsonapi/extras. Dans cette section, vous pouvez modifier le préfixe des routes en remplaçant /jsonapi par /api dans le champ « Path prefix ».

Sous la section « Resource overrides », une liste des entités disponibles sera affichée. Vous pouvez personnaliser les routes en modifiant par exemple /api/node/article en /api/article, définir quels champs doivent être exposés, utiliser des alias pour les champs (comme tags au lieu de field_tags), et améliorer la sortie de l’API. Pour apporter ces modifications, cliquez sur « Overwrite » et ajustez les paramètres de l’entité selon vos besoins.

Configuration de Simple OAuth

Pour configurer Simple OAuth, commencez par définir les durées d’expiration des tokens. Accédez à /admin/config/people/simple_oauth et configurez les paramètres suivants :

Access Token Expiration Time : Définissez le temps d’expiration par défaut pour les nouveaux tokens d’accès, exprimé en secondes (par exemple, 1209600 secondes).
Authorization Code Expiration Time : Définissez le temps d’expiration par défaut pour les nouveaux codes d’autorisation, également en secondes. Utilisez la même valeur que pour les tokens d’accès si vous n’êtes pas certain.
Refresh Token Expiration Time : Définissez le temps d’expiration par défaut pour les tokens de rafraîchissement, en secondes.
Token Batch Size : Indiquez le nombre de tokens expirés à supprimer par lot lors de l’exécution de cron (mettez à 0 pour désactiver).

Ensuite, faites défiler jusqu’en bas de la page, cliquez sur « Generate keys », et suivez les instructions pour définir un chemin de stockage sécurisé pour les clés, par exemple ../config/jwt.

Assurez-vous d’avoir les droits d’écriture sur ce répertoire ; sinon, exécutez la commande suivante pour ajuster les permissions :

chmod -R 777 ../config/jwt

Création et configuration du consumer

Ajouter un rôle : accédez à admin/people/roles ; cliquez sur « Add role » et nommez-le par exemple « OAUTH_ROLE ».
Configurer les permissions du rôle : accédez à admin/people/permissions et donnez au rôle « OAUTH_ROLE » les permissions que vous jugez nécessaire y compris ‘Access JSON:API Routes‘ (sans cette permission spécifique ajoutée par le module JSON:API Permission Access , les utilisateurs, à l’exception des administrateurs, ne pourront pas accéder aux données des endpoints JSON).
Ajouter un consumer : accédez à admin/config/services/consumer ; cliquez sur « Add consumer » et remplissez les informations nécessaires (label, client ID, client Secret etc.). Puis dans la section ‘Scopes’ associez le consumer au rôle ‘OAUTH_ROLE’.

Pour cet exemple, le client_id est QOf6alZN9a9ZB2bLG0o9qVPeNKCAeMB6UANmcSdXie4 et le client_secret est oauth.

Génération et récupération du token

Pour obtenir un token d’accès et un token de rafraîchissement, commencez par créer un utilisateur avec le rôle approprié. Accédez à /admin/people/create, créez un utilisateur (par exemple [email protected] / John12345678) , et assignez-lui le rôle « OAUTH_ROLE ».

Ensuite, générez un token en effectuant une requête POST à l’endpoint /oauth/token. Utilisez la commande curl suivante :

curl --request POST \
  --url http://your-drupal-site/oauth/token \
  --header 'content-type: application/json' \
  --data '{ "grant_type": "password", 
            "client_id": "QOf6alZN9a9ZB2bLG0o9qVPeNKCAeMB6UANmcSdXie4",    
            "client_secret": "oauth", 
            "username": "[email protected]", 
            "password": "John12345678"
           }'

Le retour de cette requête inclura un access_token et un refresh_token. Le access_token permet d’accéder aux endpoints JSON sécurisés, tandis que le refresh_token est utilisé pour obtenir un nouveau access_token lorsque le précédent expire.

Pour accéder aux endpoints protégés, comme /api/article, utilisez le access_token dans les en-têtes de vos requêtes :

curl --request GET \
  --url http://your-drupal-site/api/article \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Assurez-vous que le token reçu est valide et permet l’accès aux données selon les permissions définies.

API userinfo

Après l’obtention d’un access token, vous pouvez utiliser l’API /oauth/userinfo pour récupérer les informations du profil de l’utilisateur associé au token. Cette API est très pratique pour valider l’identité de l’utilisateur ou obtenir des informations spécifiques sans avoir à interroger manuellement les entités utilisateur dans Drupal. Assurez-vous d’inclure l’access token dans l’en-tête Authorization pour garantir que l’utilisateur est correctement authentifié.

Pour personnaliser les informations renvoyées par l’API userinfo, vous pouvez consulter la documentation officielle.

Utilisation du Refresh Token

Après l’expiration du access token, il est possible d’obtenir un nouveau token en utilisant le refresh token sans devoir fournir à nouveau les informations de connexion de l’utilisateur. Cette fonctionnalité est gérée via le même endpoint /oauth/token, mais avec des paramètres différents. voici un exemple de requête pour rafraîchir le token :

grant_type=refresh_token : Indique que la requête doit utiliser le refresh token.
refresh_token : Le refresh token obtenu lors de la génération du premier token d’accès.
client_id et client_secret : Les informations du consumer configuré.

La requête retourne un nouveau access token et un nouveau refresh token. Ce nouveau access token est ensuite utilisé pour accéder aux endpoints sécurisés.

Il est important de noter qu’un token est également généré pour un utilisateur avec un statut “bloqué“, mais ce token n’autorise aucune action et toute tentative d’accès retournera une erreur “Not Authorized“. Seuls les comptes avec le statut “activé” reçoivent un token pleinement fonctionnel. De plus, pour toutes les requêtes autres que GET dans Drupal, un token CSRF (Cross-Site Request Forgery) est obligatoire pour sécuriser les opérations. Ce token CSRF peut être obtenu via l’API GET /session/token et doit être ajouté dans les en-têtes des requêtes sous la forme suivante : X-CSRF-Token: [votre_token_csrf].

Les tests pour ces fonctionnalités ont été réalisés en utilisant Apidog, un outil efficace pour gérer et tester les API.

Conclusion

La configuration et la sécurisation d’une API dans Drupal 10 nécessitent une attention particulière aux détails, depuis l’installation des modules indispensables jusqu’à la gestion des tokens d’accès. En suivant les étapes décrites, vous pouvez créer une API robuste et sécurisée, avec des permissions spécifiques pour les utilisateurs et des mécanismes de protection comme l’authentification OAuth2 et les tokens CSRF. Assurez-vous de configurer correctement les rôles et permissions pour contrôler l’accès aux données sensibles, et de tester vos endpoints pour garantir que seuls les utilisateurs autorisés peuvent interagir avec l’API. Cette approche garantit non seulement la fonctionnalité de votre API, mais aussi sa sécurité, un aspect essentiel dans tout environnement d’intégration moderne

Oumoul Vadly Aïdara

Développeuse fullstack * Plus de publications

Développeuse fullstack spécialisée en Systèmes d'Information Répartis , diplômée de la section informatique de la Faculté des Sciences et Techniques (FST) de l'UCAD. Je relève avec passion des défis complexes, avec une forte capacité d'adaptation et un engagement pour la collaboration en équipe. Toujours avide d'apprendre, je vise à créer un impact positif et à promouvoir l'excellence organisationnelle dans chaque projet.