Ajoutez l’authentification à votre application Passport.js (Add authentication to your Passport.js application)

Ce guide vous montrera comment intégrer Logto dans votre application avec Passport.js et la stratégie OIDC.

astuce:

• Dans ce guide, nous supposons que vous avez configuré Express avec session dans votre projet. Si ce n'est pas le cas, consultez le site web Express.js pour commencer.

Prérequis

• Un compte Logto Cloud ou un Logto auto-hébergé.
• Une application traditionnelle Logto créée.
• Un projet express avec la session configurée. Consultez le site web Express.js.

Installation

Installez le SDK Logto via votre gestionnaire de paquets préféré :

npm

npm i passport passport-openidconnect

pnpm

pnpm add passport passport-openidconnect

yarn

yarn add passport passport-openidconnect

Intégration

Initialiser Passport.js avec la stratégie OIDC

passport.ts

import passport from 'passport';
import OpenIDConnectStrategy, { type Profile, type VerifyCallback } from 'passport-openidconnect';

const endpoint = '<your-logto-endpoint>';
const appId = '<your-application-id>';
const appSecret = '<your-application-secret>';

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        issuer: `${endpoint}/oidc`,
        authorizationURL: `${endpoint}/oidc/auth`,
        tokenURL: `${endpoint}/oidc/token`,
        userInfoURL: `${endpoint}/oidc/me`,
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['profile', 'offline_access'],
      },
      (issuer: string, profile: Profile, callback: VerifyCallback) => {
        callback(null, profile);
      }
    )
  );

  passport.serializeUser((user, callback) => {
    callback(null, user);
  });

  passport.deserializeUser(function (user, callback) {
    callback(null, user as Express.User);
  });
}

Ce code initialise Passport avec la OpenIDConnectStrategy. Les méthodes serialize et deserialize sont définies à des fins de démonstration.

Assurez-vous d'initialiser et d'attacher le middleware Passport dans votre application :

your-app-entry.ts

import initPassport from './passport';

// ... autre code
initPassport();
// ... autre code
app.use(passport.authenticate('session'));
// ... autre code

Configurer les URIs de redirection

Avant d’entrer dans les détails, voici un aperçu rapide de l’expérience utilisateur finale. Le processus de connexion peut être simplifié comme suit :

1. Votre application lance la méthode de connexion.
2. L’utilisateur est redirigé vers la page de connexion Logto. Pour les applications natives, le navigateur système est ouvert.
3. 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

1. 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.
2. 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.

---

remarque:

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.

Implémenter la connexion et la déconnexion

Nous allons maintenant créer des routes spécifiques pour les processus d'authentification :

your-app-entry.ts

app.get('/sign-in', passport.authenticate('openidconnect'));
app.get(
  '/callback',
  passport.authenticate('openidconnect', {
    successReturnToOrRedirect: '/',
  })
);
app.get('/sign-out', (request, response, next) => {
  request.logout((error) => {
    if (error) {
      next(error);
      return;
    }
    response.redirect(`${endpoint}/oidc/session/end?client_id=${appId}`);
  });
});

Puis ajoutez à la page d'accueil

your-app-entry.ts

app.get('/', (request: Request, response) => {
  const { user } = request;
  response.setHeader('content-type', 'text/html');

  if (user) {
    response.end(
      `<h1>Bonjour Logto</h1><p>Connecté en tant que ${JSON.stringify(
        user
      )}, <a href="/sign-out">Déconnexion</a></p>`
    );
  } else {
    response.end(`<h1>Bonjour Logto</h1><p><a href="/sign-in">Connexion</a></p>`);
  }
});

Point de contrôle : Testez votre application

Maintenant, vous pouvez tester votre application :

1. Exécutez votre application, vous verrez le bouton de connexion.
2. Cliquez sur le bouton de connexion, le SDK initiera le processus de connexion et vous redirigera vers la page de connexion Logto.
3. Après vous être connecté, vous serez redirigé vers votre application et verrez le bouton de déconnexion.
4. Cliquez sur le bouton de déconnexion pour effacer le stockage des jetons et vous déconnecter.

Portées et revendications

Logto utilise les conventions OIDC sur les portées (scopes) et revendications (claims) pour définir les portées et revendications permettant de récupérer les informations utilisateur depuis le jeton d’identifiant (ID token) et le point de terminaison OIDC userinfo. Les termes "portée (Scope)" et "revendication (Claim)" proviennent des spécifications OAuth 2.0 et OpenID Connect (OIDC).

Pour les revendications OIDC standard, leur inclusion dans le jeton d’identifiant est strictement déterminée par les portées demandées. Les revendications étendues (telles que custom_data et organizations) peuvent être configurées en plus pour apparaître dans le jeton d’identifiant via les paramètres Jeton d’identifiant personnalisé.

En résumé, lorsque vous demandez une portée (scope), vous obtiendrez les revendications (claims) correspondantes dans les informations utilisateur. Par exemple, si vous demandez la portée `email`, vous recevrez les données `email` et `email_verified` de l’utilisateur.

Par défaut, le SDK Logto demandera toujours trois portées : `openid`, `profile` et `offline_access`, et il n’est pas possible de supprimer ces portées par défaut. Cependant, vous pouvez ajouter d’autres portées lors de la configuration de Logto :

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        // ... other options
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['openid', 'offline_access', 'profile', 'email'],
      }
      // ... other options
    )
  );
  // ... other options
}

Voici la liste des portées prises en charge et les revendications correspondantes :

Portées OIDC standard

openid (par défaut)

Nom de la revendication	Type	Description
sub	string	L'identifiant unique de l'utilisateur

profile (par défaut)

Nom de la revendication	Type	Description
name	string	Le nom complet de l'utilisateur
username	string	Le nom d'utilisateur de l'utilisateur
picture	string	URL de la photo de profil de l'utilisateur final. Cette URL DOIT référencer un fichier image (par exemple, un fichier PNG, JPEG ou GIF), plutôt qu'une page Web contenant une image. Notez que cette URL DOIT référencer spécifiquement une photo de profil de l'utilisateur final adaptée à l'affichage lors de la description de l'utilisateur final, et non une photo quelconque prise par l'utilisateur final.
created_at	number	Date de création de l'utilisateur final. Le temps est représenté par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).
updated_at	number	Date de la dernière mise à jour des informations de l'utilisateur final. Le temps est représenté par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).

D'autres revendications standard telles que 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 l'endpoint userinfo. Une différence par rapport aux revendications ci-dessus est que ces revendications ne seront retournées que si leurs valeurs ne sont pas vides, tandis que les revendications ci-dessus retourneront null si les valeurs sont vides.

remarque:

Contrairement aux revendications standard, les revendications created_at et updated_at utilisent les millisecondes au lieu des secondes.

email

Nom de la revendication	Type	Description
email	string	L'adresse e-mail de l'utilisateur
email_verified	boolean	Si l'adresse e-mail a été vérifiée

phone

Nom de la revendication	Type	Description
phone_number	string	Le numéro de téléphone de l'utilisateur
phone_number_verified	boolean	Si le numéro de téléphone a été vérifié

address

Veuillez vous référer à la spécification OpenID Connect Core 1.0 pour les détails de la revendication d'adresse.

info:

Les portées marquées (par défaut) sont toujours demandées par le SDK Logto. Les revendications sous les portées OIDC standard sont toujours incluses dans le jeton d’identifiant lorsque la portée correspondante est demandée — elles ne peuvent pas être désactivées.

Portées étendues

Les portées suivantes sont étendues par Logto et retourneront des revendications via l’endpoint userinfo. Ces revendications peuvent également être configurées pour être incluses directement dans le jeton d’identifiant via Console > JWT personnalisé. Voir Jeton d’identifiant personnalisé pour plus de détails.

custom_data

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
custom_data	object	Les données personnalisées de l'utilisateur

identities

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
identities	object	Les identités liées de l'utilisateur
sso_identities	array	Les identités SSO liées de l'utilisateur

roles

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
roles	string[]	Les rôles de l'utilisateur	✅

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
organizations	string[]	Les identifiants d’organisation auxquels l'utilisateur appartient	✅
organization_data	object[]	Les données d’organisation auxquelles l'utilisateur appartient

remarque:

Ces revendications d’organisation peuvent également être récupérées via l’endpoint userinfo lors de l’utilisation d’un jeton opaque. Cependant, les jetons opaques ne peuvent pas être utilisés comme jetons d’organisation pour accéder à des ressources spécifiques à une organisation. Voir Jeton opaque et organisations pour plus de détails.

urn:logto:scope:organization_roles

Nom de la revendication	Type	Description	Inclus dans le jeton d’identifiant par défaut
organization_roles	string[]	Les rôles d’organisation auxquels l'utilisateur appartient au format <organization_id>:<role_name>	✅

Pour aller plus loin

Parcours utilisateur final : flux d’authentification, flux de compte et flux d’organisation Configurer les connecteurs Autorisation (Authorization)