Ajoutez l’authentification à votre application Express
- Le projet d'exemple est disponible sur notre répertoire SDK.
Prérequis
- Un compte Logto Cloud ou un Logto auto-hébergé.
- Une application traditionnelle Logto créée.
Installation
Installez le SDK Logto via votre gestionnaire de paquets préféré :
- npm
- pnpm
- yarn
npm i @logto/express cookie-parser express-session
pnpm add @logto/express cookie-parser express-session
yarn add @logto/express cookie-parser express-session
Intégration
Préparer les configurations et les middlewares requis
Préparer la configuration pour le client Logto :
import { LogtoExpressConfig } from '@logto/express';
const config: LogtoExpressConfig = {
appId: '<your-application-id>',
appSecret: '<your-application-secret>',
endpoint: '<your-logto-endpoint>', // Par exemple, http://localhost:3001
baseUrl: '<your-express-app-base-url>', // Par exemple, http://localhost:3000
};
Le SDK nécessite que express-session soit configuré au préalable.
import cookieParser from 'cookie-parser';
import session from 'express-session';
app.use(cookieParser());
app.use(
session({
secret: 'random_session_key', // Remplacez par votre propre secret
cookie: { maxAge: 14 * 24 * 60 * 60 * 1000 }, // En millisecondes
})
);
Configurer les URIs de redirection
Avant de plonger dans les détails, voici un aperçu rapide de l'Expérience utilisateur. Le processus de connexion peut être simplifié comme suit :
- Votre application lance la méthode de connexion.
- L'utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
- L'utilisateur se connecte et est redirigé vers votre application (configurée comme l'URI de redirection).
Concernant la connexion basée sur la redirection
- Ce processus d'authentification (Authentication) suit le protocole OpenID Connect (OIDC), et Logto applique des mesures de sécurité strictes pour protéger la connexion utilisateur.
- Si vous avez plusieurs applications, vous pouvez utiliser le même fournisseur d’identité (Logto). Une fois que l'utilisateur se connecte à une application, Logto complétera automatiquement le processus de connexion lorsque l'utilisateur accède à une autre application.
Pour en savoir plus sur la logique et les avantages de la connexion basée sur la redirection, consultez Expérience de connexion Logto expliquée.
Dans les extraits de code suivants, nous supposons que votre application fonctionne sur http://localhost:3000/
.
Configurer les URIs de redirection
Passez à la page des détails de l'application de Logto Console. Ajoutez une URI de redirection http://localhost:3000/callback
.
Tout comme pour la connexion, les utilisateurs doivent être redirigés vers Logto pour se déconnecter de la session partagée. Une fois terminé, il serait idéal de rediriger l'utilisateur vers votre site web. Par exemple, ajoutez http://localhost:3000/
comme section d'URI de redirection après déconnexion.
Ensuite, cliquez sur "Enregistrer" pour sauvegarder les modifications.
Enregistrer les routes
Le SDK fournit une fonction utilitaire handleAuthRoutes
pour enregistrer 3 routes :
/logto/sign-in
: Connexion avec Logto./logto/sign-in-callback
: Gérer le rappel de connexion./logto/sign-out
: Déconnexion avec Logto.
Ajoutez le code suivant à votre application :
import { handleAuthRoutes } from '@logto/express';
app.use(handleAuthRoutes(config));
Implémenter la connexion et la déconnexion
Avec les routes enregistrées, implémentons maintenant les boutons de connexion et de déconnexion sur la page d'accueil. Nous devons rediriger l'utilisateur vers la route de connexion ou de déconnexion lorsque cela est nécessaire. Pour aider à cela, utilisez withLogto
pour injecter le statut d'authentification dans req.user
.
import { withLogto } from '@logto/express';
app.get('/', withLogto(config), (req, res) => {
res.setHeader('content-type', 'text/html');
if (req.user.isAuthenticated) {
res.end(
`<div>Bonjour ${req.user.claims?.sub}, <a href="/logto/sign-out">Déconnexion</a></div>`
);
} else {
res.end('<div><a href="/logto/sign-in">Connexion</a></div>');
}
});
Point de contrôle : Testez votre application
Maintenant, vous pouvez tester votre application :
- Exécutez votre application, vous verrez le bouton de connexion.
- Cliquez sur le bouton de connexion, le SDK initiera le processus de connexion et vous redirigera vers la page de connexion Logto.
- Après vous être connecté, vous serez redirigé vers votre application et verrez le bouton de déconnexion.
- Cliquez sur le bouton de déconnexion pour effacer le stockage local et vous déconnecter.
Obtenir des informations sur l'utilisateur
Afficher les informations utilisateur
Lorsque l'utilisateur est connecté, la valeur de req.user
sera un objet contenant les informations de l'utilisateur. Vous pouvez afficher ces informations dans votre application :
import { withLogto } from '@logto/express';
app.get('/', withLogto(config), (req, res) => {
response.json(request.user.claims);
});
Demander des revendications supplémentaires
Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par req.user
. Cela est dû au fait que OAuth 2.0 et OpenID Connect (OIDC) sont conçus pour suivre le principe du moindre privilège (PoLP), et Logto est construit sur ces normes.
Par défaut, des revendications limitées sont retournées. Si vous avez besoin de plus d'informations, vous pouvez demander des portées supplémentaires pour accéder à plus de revendications.
Une "revendication" est une assertion faite à propos d'un sujet ; une "portée" est un groupe de revendications. Dans le cas actuel, une revendication est une information sur l'utilisateur.
Voici un exemple non normatif de la relation portée - revendication :
La revendication "sub" signifie "sujet", qui est l'identifiant unique de l'utilisateur (c'est-à-dire l'ID utilisateur).
Le SDK Logto demandera toujours trois portées : openid
, profile
et offline_access
.
Pour demander des portées supplémentaires, vous pouvez ajouter des portées à la configuration :
import { LogtoExpressConfig, UserScope } from '@logto/express';
const config: LogtoExpressConfig = {
scopes: [UserScope.Email, UserScope.Phone], // Ajouter plus de portées si nécessaire
// ...other configs
};
Ensuite, vous pouvez accéder aux revendications supplémentaires dans l'objet req.user
:
import { withLogto } from '@logto/express';
app.get('/', withLogto(config), (req, res) => {
response.end(`User email: ${req.user.claims.email}`);
});
Revendications nécessitant des requêtes réseau
Pour éviter de surcharger le jeton d’identifiant (ID token), certaines revendications nécessitent des requêtes réseau pour être récupérées. Par exemple, la revendication custom_data
n'est pas incluse dans l'objet utilisateur même si elle est demandée dans les portées. Pour accéder à ces revendications, vous pouvez configurer l'option fetchUserInfo
:
const config: LogtoExpressConfig = {
fetchUserInfo: true,
// ...other configs
};
fetchUserInfo
, le SDK récupérera les informations de l'utilisateur en faisant une requête à l' point de terminaison userinfo après que l'utilisateur se soit connecté, et user.custom_data
sera disponible une fois la requête terminée.
Portées et revendications
Logto utilise les conventions de portées et revendications OIDC pour définir les Portées et Revendications pour récupérer les informations utilisateur à partir du Jeton d’identifiant et du point de terminaison OIDC userinfo. Les termes "Portée" et "Revendication" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).
Voici la liste des Portées (Scopes) prises en charge et les Revendications (Claims) correspondantes :
openid
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
sub | string | L'identifiant unique de l'utilisateur | Non |
profile
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
name | string | Le nom complet de l'utilisateur | Non |
username | string | Le nom d'utilisateur de l'utilisateur | Non |
picture | string | URL de la photo de profil de l'utilisateur final. Cette URL DOIT faire référence à un fichier image (par exemple, un fichier image PNG, JPEG ou GIF), plutôt qu'à une page Web contenant une image. Notez que cette URL DOIT spécifiquement référencer une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, plutôt qu'une photo arbitraire prise par l'utilisateur final. | Non |
created_at | number | Heure à laquelle l'utilisateur final a été créé. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z). | Non |
updated_at | number | Heure à laquelle les informations de l'utilisateur final ont été mises à jour pour la dernière fois. Le temps est représenté comme le nombre de millisecondes depuis l'époque Unix (1970-01-01T00:00:00Z). | Non |
D'autres revendications standard incluent family_name
, given_name
, middle_name
, nickname
, preferred_username
, profile
, website
, gender
, birthdate
, zoneinfo
, et locale
seront également incluses dans la portée profile
sans avoir besoin de demander le point de terminaison userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront renvoyées que lorsque leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus renverront null
si les valeurs sont vides.
Contrairement aux revendications standard, les revendications created_at
et updated_at
utilisent des millisecondes au lieu de secondes.
email
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
string | L'adresse e-mail de l'utilisateur | Non | |
email_verified | boolean | Si l'adresse e-mail a été vérifiée | Non |
phone
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
phone_number | string | Le numéro de téléphone de l'utilisateur | Non |
phone_number_verified | boolean | Si le numéro de téléphone a été vérifié | Non |
address
Veuillez vous référer à OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.
custom_data
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
custom_data | object | Les données personnalisées de l'utilisateur | Oui |
identities
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
identities | object | Les identités liées de l'utilisateur | Oui |
sso_identities | array | Les identités SSO liées de l'utilisateur | Oui |
urn:logto:scope:organizations
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
organizations | string[] | Les identifiants d'organisation auxquels l'utilisateur appartient | Non |
organization_data | object[] | Les données d'organisation auxquelles l'utilisateur appartient | Oui |
urn:logto:scope:organization_roles
Nom de la revendication | Type | Description | Besoin d'userinfo ? |
---|---|---|---|
organization_roles | string[] | Les rôles d'organisation auxquels l'utilisateur appartient avec le format <organization_id>:<role_name> | Non |
En considérant la performance et la taille des données, si "Besoin d'userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le Jeton d’identifiant (ID token), mais sera renvoyée dans la réponse du point de terminaison userinfo.
Ressources API et organisations
Nous vous recommandons de lire d'abord 🔐 Contrôle d’accès basé sur les rôles (RBAC) pour comprendre les concepts de base de Logto RBAC et comment configurer correctement les ressources API.
Configurer le client Logto
Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :
import { UserScope } from '@logto/express';
const config: LogtoExpressConfig = {
// ...other configs
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Ajouter des ressources API
};
Chaque ressource API a ses propres permissions (portées).
Par exemple, la ressource https://shopping.your-app.com/api
a les permissions shopping:read
et shopping:write
, et la ressource https://store.your-app.com/api
a les permissions store:read
et store:write
.
Pour demander ces permissions, vous pouvez les ajouter lors de la configuration de Logto dans votre application :
import { UserScope } from '@logto/express';
const config: LogtoExpressConfig = {
// ...other configs
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
Vous pouvez remarquer que les portées sont définies séparément des ressources API. Cela est dû au fait que les Indicateurs de ressource pour OAuth 2.0 spécifient que les portées finales pour la requête seront le produit cartésien de toutes les portées de tous les services cibles.
Ainsi, dans le cas ci-dessus, les portées peuvent être simplifiées à partir de la définition dans Logto, les deux ressources API peuvent avoir les portées read
et write
sans le préfixe. Ensuite, dans la configuration de Logto :
import { UserScope } from '@logto/express';
const config: LogtoExpressConfig = {
// ...other configs
scopes: ['read', 'write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
Pour chaque ressource API, il demandera à la fois les portées read
et write
.
Il est acceptable de demander des portées qui ne sont pas définies dans les ressources API. Par exemple, vous pouvez demander la portée email
même si les ressources API n'ont pas la portée email
disponible. Les portées non disponibles seront ignorées en toute sécurité.
Après une connexion réussie, Logto émettra les portées appropriées aux ressources API en fonction des rôles de l'utilisateur.
Récupérer un jeton d’accès pour la ressource API
Pour récupérer le jeton d’accès pour une ressource API spécifique, vous pouvez utiliser la méthode getAccessToken
:
app.get(
'/fetch-access-token',
withLogto({
...config,
getAccessToken: true,
resource: 'https://shopping.your-app.com/api',
}),
(request, response) => {
console.log(request.user.accessToken);
response.json(request.user);
}
);
Cette méthode renverra un jeton d’accès JWT qui peut être utilisé pour accéder à la ressource API lorsque l’utilisateur a les Permissions associées. Si le jeton d’accès mis en cache actuel a expiré, cette méthode essaiera automatiquement d’utiliser un jeton de rafraîchissement pour obtenir un nouveau jeton d’accès.
Récupérer des jetons d’organisation
Si l'Organisation est nouvelle pour vous, veuillez lire 🏢 Organisations (Multi-tenancy) pour commencer.
Vous devez ajouter la portée UserScope.Organisations
lors de la configuration du client Logto :
import { UserScope } from '@logto/express';
const config: LogtoExpressConfig = {
// ...autres configurations
scopes: [UserScope.Organizations],
};
Une fois l'utilisateur connecté, vous pouvez récupérer le jeton d’organisation pour l'utilisateur :
app.get(
'/fetch-organization-token',
withLogto({
...config,
getOrganizationToken: true,
}),
(request, response) => {
response.json(request.user.jetons d’organisation);
}
);