Authentifizierung zu deiner Next Auth-Anwendung hinzufügen

Dieser Leitfaden zeigt dir, wie du Logto in deine Next.js-Anwendung mit Next Auth integrierst.

tipp

• In diesem Leitfaden gehen wir davon aus, dass du Next Auth in deinem Next.js-Projekt eingerichtet hast. Falls nicht, schaue dir die Next Auth Dokumentation an, um loszulegen.

Voraussetzungen

• Ein Logto Cloud Konto oder ein selbst gehostetes Logto.
• Eine traditionelle Logto-Anwendung erstellt.
• Ein Next.js-Projekt mit Next Auth, siehe die Next Auth-Dokumentation.

Integration

Next Auth-Provider konfigurieren

Bevor wir in die Details eintauchen, hier ein kurzer Überblick über die Endbenutzererfahrung. Der Anmeldeprozess kann wie folgt vereinfacht werden:

1. Deine App ruft die Anmeldemethode auf.
2. Der Benutzer wird zur Logto-Anmeldeseite umgeleitet. Bei nativen Apps wird der Systembrowser geöffnet.
3. Der Benutzer meldet sich an und wird zurück zu deiner App umgeleitet (konfiguriert als die Redirect-URI).

Bezüglich der umleitungsbasierten Anmeldung

1. Dieser Authentifizierungsprozess folgt dem OpenID Connect (OIDC) Protokoll, und Logto erzwingt strenge Sicherheitsmaßnahmen, um die Benutzeranmeldung zu schützen.
2. Wenn du mehrere Apps hast, kannst du denselben Identitätsanbieter (Logto) verwenden. Sobald sich der Benutzer bei einer App anmeldet, wird Logto den Anmeldeprozess automatisch abschließen, wenn der Benutzer auf eine andere App zugreift.

Um mehr über die Gründe und Vorteile der umleitungsbasierten Anmeldung zu erfahren, siehe Logto-Anmeldeerfahrung erklärt.

---

hinweis

In den folgenden Code-Snippets gehen wir davon aus, dass deine App unter http://localhost:3000/ läuft.

Anmelde-Redirect-URI konfigurieren

Wechseln wir zur Seite "Anwendungsdetails" der Logto-Konsole. Füge eine Redirect-URI http://localhost:3000/api/auth/callback/logto hinzu und klicke auf "Änderungen speichern".

Next Auth-Anbieter einrichten

tipp

Du kannst das "App Secret" auf der Anwendungsdetailseite in der Admin-Konsole finden und kopieren:

Ändere deine API-Routen-Konfiguration von Next Auth. Wenn du den Pages Router verwendest, befindet sich die Datei in pages/api/auth/[...nextauth].js, wenn du den App Router verwendest, befindet sich die Datei in app/api/auth/[...nextauth]/route.ts.

Das folgende ist ein Beispiel für den App Router:

Next Auth v5

import NextAuth from 'next-auth';

export const {
  handlers: { GET, POST },
  signIn,
  signOut,
  auth,
} = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oidc',
      // Du kannst den Ausstellerwert von der Logto-Anwendungsdetailseite erhalten,
      // im Feld "Issuer endpoint"
      issuer: 'https://xxxx.logto.app/oidc',
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      authorization: {
        params: { scope: 'openid offline_access profile email' },
      },
      profile(profile) {
        // Du kannst hier die Zuordnung des Benutzerprofils anpassen
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

1. Ersetze die issuer URL mit dem "Issuer endpoint" deiner Logto-Anwendung.
2. Ersetze die clientId und clientSecret mit der ID und dem Geheimnis deiner Logto-Anwendung.
3. Passe die profile Funktion an, um das Benutzerprofil dem Next Auth-Benutzerobjekt zuzuordnen, die Standardzuordnung ist im Beispiel gezeigt.

Next Auth v4

import NextAuth from 'next-auth';

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oauth',
      // Du kannst die bekannte URL von der Logto-Anwendungsdetailseite erhalten,
      // im Feld "OpenID Provider configuration endpoint"
      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) {
        // Du kannst hier die Zuordnung des Benutzerprofils anpassen
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

export { handler as GET, handler as POST };

1. Ersetze die wellKnown URL mit dem "OpenID Provider configuration endpoint" deiner Logto-Anwendung.
2. Ersetze die clientId und clientSecret mit der ID und dem Geheimnis deiner Logto-Anwendung.
3. Passe die profile Funktion an, um das Benutzerprofil dem Next Auth-Benutzerobjekt zuzuordnen, die Standardzuordnung ist im Beispiel gezeigt.
4. Denke daran, den id_token_signed_response_alg auf ES384 zu setzen.

Kontrollpunkt

Jetzt kannst du deine Anwendung testen, um zu sehen, ob die Authentifizierung wie erwartet funktioniert.

Berechtigungen und Ansprüche

Logto verwendet OIDC Berechtigungen und Ansprüche Konventionen, um die Berechtigungen und Ansprüche für das Abrufen von Benutzerinformationen aus dem ID-Token und dem OIDC userinfo endpoint zu definieren. Sowohl "Berechtigung (Scope)" als auch "Anspruch (Claim)" sind Begriffe aus den OAuth 2.0 und OpenID Connect (OIDC) Spezifikationen.

Kurz gesagt, wenn du eine Berechtigung anforderst, erhältst du die entsprechenden Ansprüche in den Benutzerinformationen. Zum Beispiel, wenn du die `email` Berechtigung anforderst, erhältst du die `email` und `email_verified` Daten des Benutzers.

Standardmäßig fordert das Logto SDK immer drei Berechtigungen an: `openid`, `profile` und `offline_access`, und es gibt keine Möglichkeit, diese Standardberechtigungen zu entfernen. Aber du kannst weitere Berechtigungen hinzufügen, wenn du Logto konfigurierst:

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      // ... other options
      authorization: { params: { scope: 'openid offline_access profile email' } },
      // ... other options
    },
  ],
});

Hier ist die Liste der unterstützten Berechtigungen (Scopes) und der entsprechenden Ansprüche (Claims):

openid

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
sub	string	Der eindeutige Identifikator des Benutzers	Nein

profile

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
name	string	Der vollständige Name des Benutzers	Nein
username	string	Der Benutzername des Benutzers	Nein
picture	string	URL des Profilbildes des Endbenutzers. Diese URL MUSS auf eine Bilddatei (zum Beispiel eine PNG-, JPEG- oder GIF-Bilddatei) verweisen und nicht auf eine Webseite, die ein Bild enthält. Beachte, dass diese URL speziell auf ein Profilfoto des Endbenutzers verweisen SOLLTE, das geeignet ist, den Endbenutzer zu beschreiben, und nicht auf ein beliebiges Foto, das vom Endbenutzer aufgenommen wurde.	Nein
created_at	number	Zeitpunkt, zu dem der Endbenutzer erstellt wurde. Die Zeit wird als Anzahl der Millisekunden seit der Unix-Epoche (1970-01-01T00:00:00Z) dargestellt.	Nein
updated_at	number	Zeitpunkt, zu dem die Informationen des Endbenutzers zuletzt aktualisiert wurden. Die Zeit wird als Anzahl der Millisekunden seit der Unix-Epoche (1970-01-01T00:00:00Z) dargestellt.	Nein

Andere Standardansprüche wie family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo und locale werden ebenfalls im profile-Scope enthalten sein, ohne dass der userinfo-Endpunkt angefordert werden muss. Ein Unterschied im Vergleich zu den oben genannten Ansprüchen besteht darin, dass diese Ansprüche nur zurückgegeben werden, wenn ihre Werte nicht leer sind, während die oben genannten Ansprüche null zurückgeben, wenn die Werte leer sind.

hinweis

Im Gegensatz zu den Standardansprüchen verwenden die Ansprüche created_at und updated_at Millisekunden anstelle von Sekunden.

email

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
email	string	Die E-Mail-Adresse des Benutzers	Nein
email_verified	boolean	Ob die E-Mail-Adresse verifiziert wurde	Nein

phone

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
phone_number	string	Die Telefonnummer des Benutzers	Nein
phone_number_verified	boolean	Ob die Telefonnummer verifiziert wurde	Nein

address

Bitte siehe OpenID Connect Core 1.0 für die Details des Adressanspruchs.

custom_data

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
custom_data	object	Die benutzerdefinierten Daten des Benutzers	Ja

identities

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
identities	object	Die verknüpften Identitäten des Benutzers	Ja
sso_identities	array	Die verknüpften SSO-Identitäten des Benutzers	Ja

urn:logto:scope:organizations

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
organizations	string[]	Die Organisations-IDs, denen der Benutzer angehört	Nein
organization_data	object[]	Die Organisationsdaten, denen der Benutzer angehört	Ja

urn:logto:scope:organization_roles

Anspruchsname	Typ	Beschreibung	Benötigt userinfo?
organization_roles	string[]	Die Organisationsrollen, denen der Benutzer angehört, im Format <organization_id>:<role_name>	Nein

---

In Anbetracht der Leistung und der Datengröße bedeutet "Benötigt userinfo?" "Ja", dass der Anspruch nicht im ID-Token angezeigt wird, sondern in der Antwort des userinfo-Endpunkts zurückgegeben wird.

Weiterführende Lektüre

Endbenutzerflüsse: Authentifizierungsflüsse, Kontoflüsse und Organisationsflüsse Connectors konfigurieren Schütze deine API