Aller au contenu principal

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

astuce:

Prérequis

Installation

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

npm i @logto/next

Intégration

Préparer les configurations

Préparez la configuration pour le client Logto :

app/logto.ts
import { LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
appId: '<your-application-id>',
appSecret: '<your-app-secret-copied-from-console>',
endpoint: '<your-logto-endpoint>', // Par exemple http://localhost:3001
baseUrl: '<your-nextjs-app-base-url>', // Par exemple http://localhost:3000
cookieSecret: 'complex_password_at_least_32_characters_long',
cookieSecure: process.env.NODE_ENV === 'production',
};

Remarque :
Si vous utilisez une variable d'environnement pour cookieSecret (par exemple, process.env.LOGTO_COOKIE_SECRET), assurez-vous que la valeur comporte au moins 32 caractères. Si cette exigence n'est pas respectée, Logto générera l'erreur suivante lors de la compilation ou de l'exécution :

TypeError: Either sessionWrapper or encryptionKey must be provided for CookieStorage

Pour éviter cette erreur, assurez-vous que la variable d'environnement est correctement définie ou fournissez une valeur de secours d'une longueur minimale de 32 caractères.

Configurer les URI 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.

URI de redirection dans Logto Console

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.

Gérer le callback

Après la connexion de l'utilisateur, Logto le redirigera vers l'URI de redirection configurée ci-dessus. Cependant, il reste encore des étapes à effectuer pour que votre application fonctionne correctement.

Nous fournissons une fonction utilitaire handleSignIn pour gérer le callback de connexion :

app/callback/route.ts
import { handleSignIn } from '@logto/next/server-actions';
import { redirect } from 'next/navigation';
import { NextRequest } from 'next/server';
import { logtoConfig } from '../logto';

export async function GET(request: NextRequest) {
const searchParams = request.nextUrl.searchParams;
await handleSignIn(logtoConfig, searchParams);

redirect('/');
}

Implémenter la connexion et la déconnexion

Implémenter les boutons de connexion et de déconnexion

Dans Next.js App Router, les événements sont gérés dans les composants client, nous devons donc d'abord créer deux composants : SignIn et SignOut.

app/sign-in.tsx
'use client';

type Props = {
onSignIn: () => Promise<void>;
};

const SignIn = ({ onSignIn }: Props) => {
return (
<button
onClick={() => {
onSignIn();
}}
>
Sign In
</button>
);
};

export default SignIn;
app/sign-out.tsx
'use client';

type Props = {
onSignOut: () => Promise<void>;
};

const SignOut = ({ onSignOut }: Props) => {
return (
<button
onClick={() => {
onSignOut();
}}
>
Sign Out
</button>
);
};

export default SignOut;

N'oubliez pas d'ajouter 'use client' en haut du fichier pour indiquer que ces composants sont des composants client.

Ajouter les boutons à la page d'accueil

remarque:

Il n'est pas autorisé de définir des Actions Serveur annotées "use server" en ligne dans les Composants Client. Nous devons les transmettre via des props depuis un Composant Serveur.

Ajoutons maintenant les boutons de connexion et de déconnexion sur votre page d'accueil. Nous devons appeler les actions serveur du SDK lorsque cela est nécessaire. Pour cela, utilisez getLogtoContext pour récupérer le statut d'authentification.

app/page.tsx
import { getLogtoContext, signIn, signOut } from '@logto/next/server-actions';
import SignIn from './sign-in';
import SignOut from './sign-out';
import { logtoConfig } from './logto';

export default async function Home() {
const { isAuthenticated, claims } = await getLogtoContext(logtoConfig);

return (
<nav>
{isAuthenticated ? (
<p>
Bonjour, {claims?.sub},
<SignOut
onSignOut={async () => {
'use server';

await signOut(logtoConfig);
}}
/>
</p>
) : (
<p>
<SignIn
onSignIn={async () => {
'use server';

await signIn(logtoConfig);
}}
/>
</p>
)}
</nav>
);
}

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.

Récupérer les informations utilisateur

Afficher les informations de l'utilisateur

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

app/page.tsx
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
const { claims } = await getLogtoContext(logtoConfig);

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

Obtenir des informations utilisateur dans les gestionnaires de route API

Vous pouvez également obtenir des informations utilisateur dans les gestionnaires de route API :

app/api/profile/route.ts
import { getLogtoContext } from '@logto/next/server-actions';
import { logtoConfig } from '../../logto';

export const dynamic = 'force-dynamic';

export async function GET() {
const { claims } = await getLogtoContext(logtoConfig);

return Response.json({ claims });
}

Demander des revendications supplémentaires

Il se peut que certaines informations utilisateur soient manquantes dans l'objet retourné par getLogtoContext. 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 lors de l'initialisation du client Logto :

app/logto.ts
import { UserScope, LogtoNextConfig } from '@logto/next';

export const logtoConfig: LogtoNextConfig = {
scopes: [UserScope.Email, UserScope.Phone], // Ajoutez plus de portées si nécessaire
// ...other configs
});

Ensuite, vous pouvez accéder aux revendications supplémentaires dans la réponse du contexte :

app/page.tsx
export default async function Home() {
const { claims: { email } = {}, } = await getLogtoContext(logtoConfig);

return (
<div>
{email && <p>Email : {email}</p>}
</div>
);
};

export default Home;

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 :

app/page.tsx
export default async function Home() {
const { userInfo } = await getLogtoContext(logtoConfig, { fetchUserInfo: true });
return (
<div>
{userInfo && <p>Email : {userInfo.email}</p>}
</div>
);
};

export default Home;
En configurant 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 userInfo 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 prises en charge et les revendications correspondantes :

openid

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
substringL'identifiant unique de l'utilisateurNon

profile

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
namestringLe nom complet de l'utilisateurNon
usernamestringLe nom d'utilisateur de l'utilisateurNon
picturestringURL 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, plutôt qu'une photo arbitraire prise par l'utilisateur final.Non
created_atnumberDate de création de l'utilisateur final. L'heure est représentée par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).Non
updated_atnumberDate de la dernière mise à jour des informations de l'utilisateur final. L'heure est représentée par le nombre de millisecondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z).Non

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 revendicationTypeDescriptionBesoin de userinfo ?
emailstringL'adresse e-mail de l'utilisateurNon
email_verifiedbooleanSi l'adresse e-mail a été vérifiéeNon

phone

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
phone_numberstringLe numéro de téléphone de l'utilisateurNon
phone_number_verifiedbooleanSi le numéro de téléphone a été vérifiéNon

address

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

custom_data

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
custom_dataobjectLes données personnalisées de l'utilisateurOui

identities

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
identitiesobjectLes identités liées de l'utilisateurOui
sso_identitiesarrayLes identités SSO liées de l'utilisateurOui

roles

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
rolesstring[]Les rôles (Roles) de l'utilisateurNon

urn:logto:scope:organizations

Nom de la revendicationTypeDescriptionBesoin de userinfo ?
organizationsstring[]Les identifiants des organisations (Organizations) auxquelles l'utilisateur appartientNon
organization_dataobject[]Les données des organisations (Organizations) auxquelles l'utilisateur appartientOui
remarque:

Ces revendications d'organisation peuvent également être récupérées via l'endpoint userinfo lors de l'utilisation d'un jeton opaque (Opaque token). Cependant, les jetons opaques ne peuvent pas être utilisés comme jetons d’organisation (Organization tokens) 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 revendicationTypeDescriptionBesoin de userinfo ?
organization_rolesstring[]Les rôles d'organisation (Organization roles) de l'utilisateur au format <organization_id>:<role_name>Non

En tenant compte des performances et de 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 (ID token), mais sera retournée dans la réponse de l'endpoint 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 client Logto

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

app/logto.ts
export const logtoConfig = {
// ...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 :

app/logto.ts
export const logtoConfig = {
// ...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 :

app/logto.ts
export const logtoConfig = {
// ...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.

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 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 :

remarque:

Il n'est pas autorisé de définir des Actions Serveur annotées "use server" en ligne dans les Composants Client. Nous devons les transmettre via des props depuis un Composant Serveur.

app/page.ts
import { getAccessToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetAccessToken from './get-access-token';

export default async function Home() {
return (
<main>
<GetAccessToken
onGetAccessToken={async () => {
'use server';

return getAccessToken(logtoConfig, 'https://shopping.your-app.com/api');
}}
/>
</main>
);
}
app/get-access-token.ts
'use client';

type Props = {
onGetAccessToken: () => Promise<string>;
};

const GetAccessToken = ({ onGetAccessToken }: Props) => {
return (
<button
onClick={async () => {
const token = await onGetAccessToken();
console.log(token);
}}
>
Obtenir le jeton d’accès (voir le journal de la console)
</button>
);
};

export default GetAccessToken;

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.

Si vous devez récupérer un jeton d’accès dans le composant serveur, vous pouvez utiliser la fonction getAccessTokenRSC :

app/page.tsx
// Importation des fonctions nécessaires
import { getAccessTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
const accessToken = await getAccessTokenRSC(logtoConfig, 'https://shopping.your-app.com/api');

return (
<main>
<p>Jeton d’accès : {accessToken}</p>
</main>
);
}
Limitation du cache des jetons RSC:

Les React Server Components ne peuvent pas écrire de cookies (limitation Next.js). Bien que getAccessTokenRSC rafraîchisse toujours les jetons expirés à l’aide du jeton de rafraîchissement, le nouveau jeton d’accès ne sera pas conservé dans le cookie de session. Cela signifie que chaque requête RSC peut déclencher un rafraîchissement du jeton si le jeton mis en cache a expiré.

Solutions :

  1. Utiliser des composants client avec Server Actions – Appelez getAccessToken depuis un composant client via Server Actions, ce qui permet de mettre à jour les cookies.
  2. Utiliser un stockage de session externe – Configurez un sessionWrapper avec un stockage Redis/KV. Le cookie ne stocke qu’un identifiant de session fixe tandis que les données de jeton résident dans le stockage externe, permettant à RSC de conserver les jetons rafraîchis. Voir Utiliser un stockage de session externe ci-dessous.

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 :

app/logto.ts
import { UserScope } from '@logto/next';

export const logtoConfig = {
// ...other configs
scopes: [UserScope.Organisations],
};

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

remarque:

Il n'est pas autorisé de définir des Actions Serveur annotées "use server" en ligne dans les Composants Client. Nous devons les transmettre via des props depuis un Composant Serveur.

app/page.ts
import { getOrganizationToken } from '@logto/next/server-actions';
import { logtoConfig } from './logto';
import GetOrganizationToken from './get-organization-token';

export default async function Home() {
return (
<main>
<GetOrganizationToken
onGetOrganizationToken={async () => {
'use server';

return getOrganizationToken(logtoConfig, 'organization-id');
}}
/>
</main>
);
}
app/get-organization-token.ts
'use client';

type Props = {
onGetOrganizationToken: () => Promise<string>;
};

const GetOrganizationToken = ({ onGetOrganizationToken }: Props) => {
return (
<button
onClick={async () => {
const token = await onGetOrganizationToken();
console.log(token);
}}
>
Obtenir le jeton d’organisation (voir le journal de la console)
</button>
);
};

export default GetOrganizationToken;

Si vous devez récupérer un jeton d’organisation dans le composant serveur, vous pouvez utiliser la fonction getOrganizationTokenRSC :

app/page.tsx
// Importation des fonctions nécessaires
import { getOrganizationTokenRSC } from '@logto/next/server-actions';
import { logtoConfig } from './logto';

export default async function Home() {
const token = await getOrganizationTokenRSC(logtoConfig, 'organization-id');

return (
<main>
<p>Jeton d’organisation : {token}</p>
</main>
);
}
Limitation du cache des jetons RSC:

Comme pour getAccessTokenRSC, le jeton d’organisation rafraîchi ne sera pas conservé dans RSC. Voir solutions ci-dessus.

Utiliser un stockage de session externe

Le SDK utilise par défaut des cookies pour stocker les données de session chiffrées. Cette approche est sécurisée, ne nécessite aucune infrastructure supplémentaire et fonctionne particulièrement bien dans des environnements serverless comme Vercel.

Cependant, il peut arriver que vous ayez besoin de stocker les données de session de manière externe. Par exemple, lorsque vos données de session deviennent trop volumineuses pour les cookies, notamment lorsque vous devez maintenir plusieurs sessions d'organisation actives simultanément. Dans ces cas, vous pouvez implémenter un stockage de session externe en utilisant l'option sessionWrapper :

import { MemorySessionWrapper } from './storage';

export const config = {
// ...
sessionWrapper: new MemorySessionWrapper(),
};
import { randomUUID } from 'node:crypto';

import { type SessionWrapper, type SessionData } from '@logto/next';

// Cette implémentation utilise un stockage en mémoire simple.
// Dans un environnement de production, il est recommandé d'utiliser une solution de stockage plus persistante, comme Redis ou une base de données.

export class MemorySessionWrapper implements SessionWrapper {
private readonly storage = new Map<string, unknown>();
private currentSessionId?: string;

async wrap(data: unknown, _key: string): Promise<string> {
// Réutilise l'ID de session existant si disponible, ne génère un nouvel ID que pour les utilisateurs qui se connectent pour la première fois.
// Ceci est important pour les environnements où les cookies ne peuvent pas être mis à jour (par exemple, React Server Components),
// car l'ID de session dans le cookie doit rester stable tandis que les données dans le stockage externe peuvent être mises à jour.
const sessionId = this.currentSessionId ?? randomUUID();
this.currentSessionId = sessionId;
this.storage.set(sessionId, data);
return sessionId;
}

async unwrap(value: string, _key: string): Promise<SessionData> {
if (!value) {
return {};
}

// Stocke l'ID de session pour une éventuelle réutilisation dans wrap()
this.currentSessionId = value;
const data = this.storage.get(value);
return data ?? {};
}
}

L'implémentation ci-dessus utilise un stockage en mémoire simple. En environnement de production, il est conseillé d'utiliser une solution de stockage plus persistante, telle que Redis ou une base de données.

Redirection automatique vers la connexion en cas d’utilisateur non autorisé

astuce:

Le helper signIn modifie les cookies pour établir la session de connexion, il ne peut donc pas être invoqué directement dans un React Server Component (RSC). Pour déclencher automatiquement la connexion lorsqu’un RSC détecte un utilisateur non autorisé, appelez signIn dans un gestionnaire de route dédié et redirigez vers cette route.

app/sign-in/route.ts
// Importation des fonctions nécessaires
import { signIn } from '@logto/next/server-actions';
import { logtoConfig } from '../../logto';

export async function GET() {
await signIn(logtoConfig);
}
app/protected/page.tsx
// Importation des fonctions nécessaires
import { getLogtoContext } from '@logto/next/server-actions';
import { redirect } from 'next/navigation';
import { logtoConfig } from '../logto';

export default async function ProtectedPage() {
const { isAuthenticated } = await getLogtoContext(logtoConfig);

if (!isAuthenticated) {
redirect('/sign-in');
}

return <div>Contenu protégé</div>;
}

Pour aller plus loin

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