Ajoutez l’authentification à votre application Auth.js (Next Auth)

Ce guide vous montrera comment intégrer Logto dans votre application Next.js avec Auth.js, précédemment connu sous le nom de Next Auth.

astuce:

Dans ce guide, nous supposons que vous avez configuré Next Auth dans votre projet Next.js. Si ce n'est pas le cas, consultez la documentation de Next Auth pour commencer.

Prérequis

Un compte Logto Cloud ou un Logto auto-hébergé.
Une application traditionnelle Logto créée.
Un projet Next.js avec Auth.js, consultez la documentation Auth.js.

Installation

Installez Auth.js via votre gestionnaire de paquets préféré :

npm
pnpm
yarn

npm i next-auth@beta

pnpm add next-auth@beta

yarn add next-auth@beta

Voir la documentation Auth.js pour plus de détails.

Intégration

Configurer le fournisseur Auth.js

astuce:

Vous pouvez trouver et copier le "Secret de l'application" depuis la page des détails de l'application dans la Console d'administration :

Modifiez votre configuration de route API d'Auth.js, ajoutez Logto en tant que fournisseur OIDC :

Auth.js v5
Next Auth v4

./app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth';
export const { GET, POST } = handlers;

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oidc',
      // Vous pouvez obtenir la valeur de l'émetteur depuis la page Détails de l'application Logto,
      // dans le champ "Endpoint de l'émetteur"
      issuer: 'https://xxxx.logto.app/oidc',
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      authorization: {
        params: { scope: 'openid offline_access profile email' },
      },
      profile(profile) {
        // Vous pouvez personnaliser le mappage du profil utilisateur ici
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

Remplacez l'URL issuer par le "Endpoint de l'émetteur" de votre application Logto.
Remplacez le clientId et le clientSecret par l'ID et le secret de votre application Logto.
Personnalisez la fonction profile pour mapper le profil utilisateur à l'objet utilisateur de Next Auth, le mappage par défaut est montré dans l'exemple.

Ensuite, vous pouvez également ajouter un Middleware optionnel pour maintenir la session active :

./middleware.ts
export { auth as middleware } from '@/auth';

app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth';

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oauth',
      // Vous pouvez obtenir l'URL bien connue depuis la page Détails de l'application Logto,
      // dans le champ "Endpoint de configuration du fournisseur OpenID"
      wellKnown: 'https://xxxx.logto.app/oidc/.well-known/openid-configuration',
      authorization: { params: { scope: 'openid offline_access profile email' } },
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      client: {
        id_token_signed_response_alg: 'ES384',
      },
      profile(profile) {
        // Vous pouvez personnaliser le mappage du profil utilisateur ici
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

export { handler as GET, handler as POST };

Remplacez l'URL wellKnown par le "Endpoint de configuration du fournisseur OpenID" de votre application Logto.
Remplacez le clientId et le clientSecret par l'ID et le secret de votre application Logto.
Personnalisez la fonction profile pour mapper le profil utilisateur à l'objet utilisateur de Next Auth, le mappage par défaut est montré dans l'exemple.
N'oubliez pas de définir le id_token_signed_response_alg sur ES384.

Vous pouvez trouver plus de détails dans la documentation Auth.js.

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).

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.

remarque:

Dans les extraits de code suivants, nous supposons que votre application fonctionne sur http://localhost:3000/.

Passons à la page des détails de l'application de Logto Console. Ajoutez une URI de redirection http://localhost:3000/api/auth/callback/logto et cliquez sur "Enregistrer les modifications".

app/components/sign-in.tsx
import { signIn } from '@/auth';

export default function SignIn() {
  return (
    <form
      action={async () => {
        'use server';
        await signIn('logto');
      }}
    >
      <button type="submit">Se connecter</button>
    </form>
  );
}

app/components/sign-out.tsx
import { signOut } from '@/auth';

export function SignOut() {
  return (
    <form
      action={async () => {
        'use server';
        await signOut();
      }}
    >
      <button type="submit">Se déconnecter</button>
    </form>
  );
}

app/page.tsx
import SignIn from './components/sign-in';
import SignOut from './components/sign-out';
import { auth } from '@/auth';

export default function Home() {
  const session = await auth();

  return <div>{session?.user ? <SignOut /> : <SignIn />}</div>;
}

Ci-dessus est un exemple simple, vous pouvez consulter la documentation Auth.js pour plus de détails.

Point de contrôle

Maintenant, vous pouvez tester votre application pour voir si l'authentification fonctionne comme prévu.

Récupérer les informations utilisateur

Afficher les informations de l'utilisateur

Lorsque l'utilisateur est connecté, la valeur de retour de auth() sera un objet contenant les informations de l'utilisateur. Vous pouvez afficher ces informations dans votre application :

app/page.tsx
import { auth } from '@/auth';

export default async function Home() {
  const session = await auth();

  return (
    <main>
      {session?.user && (
        <div>
          <h2>Revendications :</h2>
          <table>
            <thead>
              <tr>
                <th>Nom</th>
                <th>Valeur</th>
              </tr>
            </thead>
            <tbody>
              {Object.entries(session.user).map(([key, value]) => (
                <tr key={key}>
                  <td>{key}</td>
                  <td>{String(value)}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}
    </main>
  );
}

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par auth(). 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.

info:

Une "revendication" est une affirmation 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 :

astuce:

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 configurer les paramètres du fournisseur Logto :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email',
        },
      },
      // ...
    },
  ],
});

Revendications nécessitant des requêtes réseau

Pour éviter de surcharger le jeton d’identifiant, 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 devez effectuer une requête réseau pour récupérer les informations de l'utilisateur.

Obtenir le jeton d’accès

Mettez à jour la configuration NextAuth pour que nous puissions obtenir le jeton d’accès :

./auth.ts
export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token;
      }
      return token;
    },
    async session({ session, token }) {
      // Injecter le jeton d’accès dans l'objet session
      session.accessToken = token.accessToken;
      return session;
    },
  },
});

Récupérer les informations de l'utilisateur

Accédez maintenant au point de terminaison des informations utilisateur OIDC avec le jeton d’accès :

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();
  // Remplacez l'URL par votre point de terminaison Logto, doit se terminer par `/oidc/me`
  const response = await fetch('https://xxx.logto.app/oidc/me', {
    headers: {
      Authorization: `Bearer ${session?.accessToken}`,
    },
  });
  const user = await response.json();
  console.log(user);

  // ...
}

Ci-dessus est un exemple simple. N'oubliez pas de gérer les cas d'erreur.

Rafraîchissement du jeton d’accès

Un jeton d’accès est valide pour une courte période de temps. Par défaut, Next.js n'en récupérera qu'un lorsque la session est créée. Pour implémenter le rafraîchissement automatique du jeton d’accès, voir Rotation du jeton de rafraîchissement.

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 prises en charge et les revendications correspondantes :

openid

Nom de la revendication	Type	Description	Besoin de userinfo ?
sub	`string`	L'identifiant unique de l'utilisateur	Non

profile

Nom de la revendication	Type	Description	Besoin de 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 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 écoulées 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 écoulées 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.

remarque:

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 de userinfo ?
email	`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 de 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 de userinfo ?
custom_data	`object`	Les données personnalisées de l'utilisateur	Oui

identities

Nom de la revendication	Type	Description	Besoin de 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

roles

Nom de la revendication	Type	Description	Besoin de userinfo ?
roles	`string[]`	Les rôles de l'utilisateur	Non

urn:logto:scope:organizations

Nom de la revendication	Type	Description	Besoin de 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 de 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 de userinfo ?" est "Oui", cela signifie que la revendication n'apparaîtra pas dans le jeton d’identifiant, mais sera renvoyée dans la réponse du point de terminaison userinfo.

Ressources API

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 fournisseur Logto

Une fois que vous avez configuré les ressources API, vous pouvez les ajouter lors de la configuration de Logto dans votre application :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email',
          resource: 'https://shopping.your-app.com/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 :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email shopping:read shopping:write',
          resource: 'https://shopping.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 :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile read write',
          resource: 'https://shopping.your-app.com/api',
        },
      },
      // ...
    },
  ],
});

Pour chaque ressource API, il demandera à la fois les portées read et write.

remarque:

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 le jeton d’accès pour la ressource API

Auth.js ne récupérera le jeton d’accès qu'une seule fois sans paramètre de ressource. Nous devons implémenter nous-mêmes la récupération du jeton d’accès.

Obtenir le jeton de rafraîchissement

Mettez à jour la configuration du fournisseur Logto, ajoutez le paramètre "prompt" et définissez-le sur consent, et assurez-vous que la portée offline_access est incluse :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  authorization: {
    params: {
      prompt: 'consent',
      scope: 'openid offline_access shopping:read shopping:write',
      resource: 'https://shopping.your-app.com/api',
      // ...
    },
  },
  // ...
});

Ajoutez ensuite un callback pour enregistrer le refresh_token dans la session :

./auth.ts
export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        // ...
        token.refreshToken = account.refresh_token;
      }
      return token;
    },
    async session({ session, token }) {
      // ...
      session.refreshToken = token.refreshToken;
      return session;
    },
  },
});

Récupérer le jeton d’accès

Avec le refresh_token, nous pouvons récupérer le jeton d’accès à partir du point de terminaison de jeton OIDC de Logto.

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();

  if (session?.refreshToken) {
    // Remplacez l'ID et le secret de l'application par les vôtres, vous pouvez vérifier la section "Integration".
    const basicAuth = Buffer.from('<logto-app-id>:<logto-app-secret>').toString('base64');

    // Remplacez l'URL par votre point de terminaison Logto, doit se terminer par `/oidc/token`
    const response = await fetch('https://xxx.logto.app/oidc/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: `Basic ${basicAuth}`,
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: session.refreshToken,
        resource: 'https://shopping.your-app.com/api',
      }).toString(),
    });

    const data = await response.json();
    console.log(data.access_token);
  }

  // ...
}

Récupérer les jetons d’organisation

Si l'Organisation est nouvelle pour vous, veuillez lire 🏢 Organisations (Multi-tenancy) pour commencer.

Vous devez ajouter la portée urn:logto:scope:organizations lors de la configuration du client Logto :

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access urn:logto:scope:organizations',
        },
      },
      // ...
    },
  ],
});

Une fois l'utilisateur connecté, vous pouvez récupérer le jeton d’organisation pour l'utilisateur :

Similaire au jeton d’accès pour les ressources API, nous pouvons utiliser le jeton de rafraîchissement pour récupérer le jeton d’accès de l’organisation.

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();

  if (session?.refreshToken) {
    // Remplacez l'ID et le secret de l'application par les vôtres, vous pouvez vérifier la section "Integration".
    const basicAuth = Buffer.from('<logto-app-id>:<logto-app-secret>').toString('base64');

    // Remplacez l'URL par votre point de terminaison Logto, elle doit se terminer par `/oidc/token`
    const response = await fetch('https://xxx.logto.app/oidc/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: `Basic ${basicAuth}`,
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: session.refreshToken,
        resource: 'urn:logto:scope:organizations',
        organization_id: 'organization-id',
      }).toString(),
    });

    const data = await response.json();
    console.log(data.access_token);
  }

  // ...
}

Lectures complémentaires

Flux utilisateur final : flux d'authentification, flux de compte et flux d'organisation Configurer les connecteurs Protéger votre API

Migration de l'intégration Logto de NextAuth.js v4 à v5

Prérequis​

Installation​

Intégration​

Configurer le fournisseur Auth.js​

Configurer l'URI de redirection de connexion​

Concernant la connexion basée sur la redirection​

Implémenter la connexion et la déconnexion​

Implémenter le bouton de connexion et de déconnexion​

Afficher le bouton de connexion et de déconnexion sur la page​

Point de contrôle​

Récupérer les informations utilisateur​

Afficher les informations de l'utilisateur​

Demander des revendications supplémentaires​

Revendications nécessitant des requêtes réseau​

Obtenir le jeton d’accès​

Récupérer les informations de l'utilisateur​

Rafraîchissement du jeton d’accès​

Portées et revendications​

Ressources API​

Configurer le fournisseur Logto​

Récupérer le jeton d’accès pour la ressource API​

Obtenir le jeton de rafraîchissement​

Récupérer le jeton d’accès​

Récupérer les jetons d’organisation​

Lectures complémentaires​

Prérequis

Installation

Intégration

Configurer le fournisseur Auth.js

Configurer l'URI de redirection de connexion

Concernant la connexion basée sur la redirection

Implémenter la connexion et la déconnexion

Implémenter le bouton de connexion et de déconnexion

Afficher le bouton de connexion et de déconnexion sur la page

Point de contrôle

Récupérer les informations utilisateur

Afficher les informations de l'utilisateur

Demander des revendications supplémentaires

Revendications nécessitant des requêtes réseau

Obtenir le jeton d’accès

Récupérer les informations de l'utilisateur

Rafraîchissement du jeton d’accès

Portées et revendications

Ressources API

Configurer le fournisseur Logto

Récupérer le jeton d’accès pour la ressource API

Obtenir le jeton de rafraîchissement

Récupérer le jeton d’accès

Récupérer les jetons d’organisation

Lectures complémentaires