Créer un framework SDK basé sur Node.js pour Logto en quelques minutes

Précédemment dans cet article, nous avons créé un SDK web pour Logto en quelques minutes. Maintenant, concentrons-nous sur Node.js, une autre plateforme populaire pour les développeurs JavaScript.

Dans ce guide, nous vous guiderons à travers les étapes pour créer un simple SDK Express pour Logto en utilisant @logto/node. Ce SDK implémentera le flux de connexion, et vous pouvez suivre les mêmes étapes pour créer un SDK pour toute autre plateforme basée sur Node.js, comme Koa, Next.js, NestJS, etc.

Le flux de connexion#

Avant de commencer, passons en revue le flux de connexion dans Logto. Le flux de connexion comprend les étapes suivantes :

1. Redirection vers Logto : L'utilisateur est redirigé vers la page de connexion de Logto.
2. Authentification : L'utilisateur saisit ses informations d'identification et s'authentifie avec Logto.
3. Redirection vers votre application : Après une authentification réussie, l'utilisateur est redirigé vers votre application avec un code d'autorisation.
4. Échange de code : Votre application échange le code d'autorisation contre des jetons et stocke les jetons comme état d'authentification.

Brève introduction de @logto/node#

Similaire à @logto/browser, le package @logto/node expose une classe LogtoClient qui fournit les fonctionnalités principales de Logto, y compris des méthodes pour le flux de connexion :

1. signIn() : Génère l'URL d'authentification OIDC et redirige vers celle-ci.
2. handleSignInCallback() : Vérifie et analyse l'URL de rappel et extrait le code d'autorisation, puis échange le code contre des jetons en appelant l'endpoint de jeton.
3. getContext() : Obtient le contexte de la requête actuelle en fonction du cookie de session, y compris l'état d'authentification et les informations d'utilisateur.

Créer le SDK Express#

Dans le SDK, nous fournirons deux gestionnaires de routes (/sign-in et /sign-in-callback) ainsi qu'un middleware withLogto :

1. /sign-in : Un gestionnaire de route qui déclenche le flux de connexion avec une réponse qui redirige vers l'URL d'authentification OIDC.
2. /sign-in-callback : Un gestionnaire de route qui traite l'URL de rappel, échange le code d'autorisation contre des jetons, les stocke, et complète le flux de connexion.
3. middleware withLogto : Un middleware qui appelle getContext() pour récupérer le contexte de la requête actuelle, y compris l'état d'authentification et les informations d'utilisateur.

Pour utiliser le SDK, vous pouvez simplement ajouter le middleware à votre application Express pour protéger les routes et utiliser les gestionnaires de routes pour déclencher le flux de connexion et traiter le rappel.

Étape 1 : Installer le package#

Tout d'abord, installez le package @logto/node en utilisant npm ou d'autres gestionnaires de packages :

Étape 2 : Préparer l'adaptateur de stockage#

Un adaptateur de stockage est requis pour initialiser l'instance LogtoClient.

En supposant que l'utilisateur du SDK a déjà configuré la session express, nous pouvons simplement implémenter la classe Storage en créant un nouveau fichier storage.ts :

Étape 3 : Implémenter les gestionnaires de routes#

La requête HTTP est sans état, donc nous devons initialiser l'instance client pour chaque requête. Préparons une fonction utilitaire pour créer l'instance client :

Dans cette fonction, nous implémentons l'adaptateur navigate ainsi que l'adaptateur ExpressStorage. L'adaptateur navigate est utilisé pour rediriger l'utilisateur vers l'URL de connexion.

Ensuite, implémentons les gestionnaires de routes, enveloppés dans une fonction handleAuthRoutes :

1. Le gestionnaire de route /auth/sign-in déclenche le flux de connexion en appelant signIn(), un état de connexion est stocké dans la session, et sera consommé par le gestionnaire de route /auth/sign-in-callback.
2. Le gestionnaire de route /auth/sign-in-callback gère l'URL de rappel et échange le code d'autorisation contre des jetons en appelant handleSignInCallback(), les jetons sont stockés dans la session par l'adaptateur ExpressStorage. Une fois l'échange terminé, l'utilisateur est redirigé vers la page d'accueil.

Étape 4 : Implémenter le middleware#

Le middleware withLogto est utilisé pour protéger les routes. Il appelle getContext() pour obtenir le contexte de la requête actuelle, y compris l'état d'authentification et les informations d'utilisateur.

La fonction getContext utilise l'adaptateur de stockage pour obtenir les jetons de la session.

Point de contrôle : utiliser le SDK#

Maintenant que vous avez créé le SDK Express pour Logto, vous pouvez l'utiliser dans votre application en ajoutant le middleware pour protéger les routes et en utilisant les gestionnaires de routes pour déclencher le flux de connexion et traiter le rappel.

Voici un exemple simple de la façon d'utiliser le SDK dans votre application Express :

Dans cet exemple, nous utilisons le middleware withLogto pour vérifier l'état d'authentification et rediriger l'utilisateur vers la page de connexion s'il n'est pas authentifié, sinon, nous affichons un message de bienvenue.

Vous pouvez consulter le projet d'exemple officiel Express ici.

Conclusion#

Dans ce guide, nous vous avons guidé à travers les étapes pour créer un SDK Express pour Logto en implémentant le flux d'authentification de base. Le SDK fourni ici est un exemple de base. Vous pouvez l'étendre en ajoutant plus de méthodes et de fonctionnalités pour répondre aux besoins de votre application.

Vous pouvez suivre les mêmes étapes pour créer un SDK pour toute autre plateforme JavaScript qui fonctionne sous Node.js.

Ressources :

1. Logto Node SDK
2. Logto Express SDK