Zum Hauptinhalt springen

Kontoeinstellungen über die Account API

Was ist die Logto Account API​

Die Logto Account API ist eine umfassende Sammlung von APIs, die Endbenutzern direkten API-Zugriff ermöglicht, ohne die Management API verwenden zu müssen. Hier die wichtigsten Punkte:

  • Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto-Profil zuzugreifen und dieses zu verwalten, ohne die Weiterleitung über die Management API zu benötigen.
  • Verwaltung von Benutzerprofilen und Identitäten: Benutzer können ihre Profile und Sicherheitseinstellungen vollständig verwalten, einschließlich der Möglichkeit, Identitätsinformationen wie E-Mail, Telefon und Passwort zu aktualisieren sowie soziale Verbindungen zu verwalten. MFA und SSO-Unterstützung folgen in Kürze.
  • Globale Zugangskontrolle: Administratoren haben vollständige, globale Kontrolle über die Zugriffseinstellungen und können jedes Feld individuell anpassen.
  • Nahtlose Autorisierung (Authorization): Autorisierung (Authorization) ist einfacher denn je! Verwende einfach client.getAccessToken(), um ein opakes Zugangstoken (Opaque token) für OP (Logto) zu erhalten, und füge es dem Authorization-Header als Bearer <access_token> hinzu.

Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig mit Logto integriert ist.

Einige häufige Anwendungsfälle sind unten aufgeführt:

  • Benutzerprofil abrufen
  • Benutzerprofil aktualisieren
  • Benutzerpasswort aktualisieren
  • Benutzeridentitäten wie E-Mail, Telefon und soziale Verbindungen aktualisieren
  • MFA-Faktoren (Verifizierungen) verwalten
  • Benutzersitzungen verwalten
  • Benutzerautorisierte Apps (Grants) verwalten

Um mehr über die verfügbaren APIs zu erfahren, besuche bitte die Logto Account API Referenz und die Logto Verification API Referenz.

hinweis:

SSO-Kontoansicht und Kontolöschungsfunktionen sind derzeit über die Logto Management APIs verfügbar. Siehe Kontoeinstellungen über die Management API für Implementierungsdetails.

Wie aktiviere ich die Account API​

Navigiere zu Konsole > Anmeldung & Konto > Account Center.

Die Account API ist standardmäßig deaktiviert, daher sind ihre Zugriffskontrollen gesperrt. Schalte Account API aktivieren ein, um sie zu aktivieren.

Nach der Aktivierung konfiguriere das Fenster für Kürzliche Authentifizierung (von 1 bis 120 Minuten; Standard: 10 Minuten) und die Berechtigungen pro Feld für Identifikatoren, Profildaten und Zugriff auf Drittanbieter-Tokens. Jedes Feld unterstützt Aus, Nur Lesen oder Bearbeiten; Standard ist Aus.

  1. Sicherheitsfelder:
    • Felder umfassen: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort, Passkeys, MFA und persönliche Zugriffstokens.
    • Sensible Operationen erfordern eine kürzliche Benutzer-Authentifizierung aus einer First-Party-Anwendung — ein Zugangstoken (Access token), dessen acr urn:logto:acr:1fa innerhalb des konfigurierten Fensters für kürzliche Authentifizierung erfüllt (siehe OIDC Step-up-Authentifizierung).
    • Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu WebAuthn Related Origins hinzu, damit Account Center und Anmeldungserlebnis Passkeys gemeinsam nutzen können. Siehe Neuen WebAuthn-Passkey verknüpfen.
  2. Profilfelder:
    • Felder umfassen: Benutzername, Name, Avatar, Profil (weitere Standard-Profilattribute) und benutzerdefinierte Daten.
    • Endbenutzer können diese ohne zusätzliche Verifizierung bearbeiten, außer Benutzername, der ebenfalls eine kürzliche Benutzer-Authentifizierung erfordert.
  3. Secret Vault:
    • Für OIDC- oder OAuth-Sozial- und Enterprise-Connectors speichert der Logto Secret Vault Drittanbieter-Zugriffs- und Auffrischungstokens (Refresh tokens) nach der Authentifizierung sicher. Apps können dann externe APIs aufrufen, z. B. Google-Kalender-Ereignisse synchronisieren, ohne dass Benutzer sich erneut anmelden müssen. Die Token-Abfrage ist automatisch verfügbar, sobald die Account API aktiviert ist.
  4. Sitzungsverwaltung:
    • Wenn aktiviert, können Benutzer ihre aktiven Sitzungen einschließlich Geräteinformationen und letzter Anmeldung einsehen und verwalten. Benutzer können auch Sitzungen widerrufen, um sich von bestimmten Geräten abzumelden.
    • Diese gleiche Berechtigung für das Feld Sitzungen steuert auch die APIs für benutzerautorisierte Apps (Grants) (Anzeigen und Widerrufen von Grants).
    • Der Zugriff auf Sitzungs- und Grant-Verwaltung erfordert die gleiche kürzliche Benutzer-Authentifizierung wie Sicherheitsfelder.

Wie greife ich auf die Account API zu​

hinweis:

Um sicherzustellen, dass das Zugangstoken (Access token) die entsprechenden Berechtigungen hat, stelle sicher, dass du die entsprechenden Berechtigungen (Scopes) in deiner Logto-Konfiguration richtig konfiguriert hast.

Zum Beispiel: Für die API POST /api/my-account/primary-email musst du die Berechtigung email konfigurieren; für die API POST /api/my-account/primary-phone die Berechtigung phone.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...andere Optionen
  // Füge die passenden Berechtigungen hinzu, die zu deinen Anwendungsfällen passen.
  scopes: [
    UserScope.Email, // Für `{POST,DELETE} /api/my-account/primary-email` APIs
    UserScope.Phone, // Für `{POST,DELETE} /api/my-account/primary-phone` APIs
    UserScope.CustomData, // Um benutzerdefinierte Daten zu verwalten
    UserScope.Address, // Um Adresse zu verwalten
    UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs
    UserScope.Profile, // Um Benutzerprofil zu verwalten
    UserScope.Sessions, // Um Benutzersitzungen und App-Grants zu verwalten
  ],
};

Zugangstoken abrufen​

Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode client.getAccessToken() verwenden, um ein Zugangstoken (Access token) abzurufen. Dieses Token ist ein opaker Token (Opaque token), das für den Zugriff auf die Account API verwendet werden kann.

Wenn du das offizielle SDK nicht verwendest, solltest du das resource für die Access Token Grant-Anfrage an /oidc/token leer lassen.

Zugriff auf die Account API mit Zugangstoken​

Du solltest das Zugangstoken im Feld Authorization der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) einfügen, wenn du mit der Account API interagierst.

Hier ein Beispiel, um die Benutzerkontoinformationen abzurufen:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Grundlegende Kontoinformationen verwalten​

Benutzerkontoinformationen abrufen​

Um Benutzerdaten abzurufen, kannst du den GET /api/my-account Endpunkt verwenden.

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

Die Antwortfelder können je nach Account Center-Einstellungen variieren.

Grundlegende Kontoinformationen aktualisieren​

Grundlegende Kontoinformationen umfassen Benutzername, Name, Avatar, benutzerdefinierte Daten und andere Profilinformationen.

Um Benutzername, Name, Avatar und customData zu aktualisieren, kannst du den PATCH /api/my-account Endpunkt verwenden.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

Um andere Profilinformationen zu aktualisieren, einschließlich familyName, givenName, middleName, nickname, profile (Profilseiten-URL), website, gender, birthdate, zoneinfo, locale und address, kannst du den PATCH /api/my-account/profile Endpunkt verwenden.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

Identifikatoren und andere sensible Informationen verwalten​

Aus Sicherheitsgründen erfordern sensible Account API-Operationen eine kürzliche Benutzer-Authentifizierung aus einer First-Party-Anwendung: Das Zugangstoken (Access token) muss ein acr enthalten, das urn:logto:acr:1fa erfüllt, und eine auth_time innerhalb des Kürzliche Authentifizierung-Fensters deines Tenants (600 Sekunden / 10 Minuten standardmäßig, konfigurierbar von 60 bis 7.200 Sekunden).

Wenn das Zugangstoken kein urn:logto:acr:1fa enthält oder älter als das Fenster ist, gibt die Account API 401 Unauthorized mit einem RFC 9470 WWW-Authenticate Header zurück (error="insufficient_user_authentication", acr_values="urn:logto:acr:1fa", max_age="<window>"). Starte eine OIDC Step-up-Authentifizierungsanfrage mit diesen Parametern und wiederhole den Aufruf mit dem neu ausgestellten Zugangstoken.

hinweis:

Das Binden einer neuen E-Mail-Adresse, Telefonnummer, sozialen Identität oder eines WebAuthn-Passkeys erfordert ebenfalls den Nachweis des Besitzes dieses neuen Identifikators oder Faktors über die Verification API und das Übergeben von newIdentifierVerificationRecordId im Request-Body, wie in jedem Abschnitt unten gezeigt.

Benutzerpasswort aktualisieren​

Um das Benutzerpasswort zu aktualisieren, kannst du den POST /api/my-account/password Endpunkt verwenden.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'
tipp:

Wie Passwörter, die während der Registrierung erstellt wurden, müssen auch Passwörter, die über die Account API gesetzt werden, der von dir konfigurierten Passwortrichtlinie in Konsole > Sicherheit > Passwortrichtlinie entsprechen. Logto gibt detaillierte Validierungsergebnisse und Fehlermeldungen zurück, wenn das Passwort die Richtlinie nicht erfüllt.

hinweis:

Um diese Methode zu verwenden, musst du den E-Mail-Connector konfigurieren und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, musst du zuerst den Besitz der E-Mail nachweisen.

Rufe den POST /api/verifications/verification-code Endpunkt auf, um einen Verifizierungscode anzufordern.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

Du findest eine verificationId in der Antwort und erhältst einen Verifizierungscode per E-Mail, den du zur Verifizierung der E-Mail verwendest.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

Nach der Verifizierung des Codes kannst du nun PATCH /api/my-account/primary-email aufrufen, um die E-Mail des Benutzers zu aktualisieren. Setze die verificationId im Request-Body als newIdentifierVerificationRecordId.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'
tipp:

Wie E-Mails, die während der Registrierung gesammelt werden, muss jede E-Mail, die über die Account API verknüpft wird, die von dir konfigurierte Blocklist in Konsole > Sicherheit > Blocklist bestehen. Logto lehnt die Anfrage ab und gibt eine detaillierte Fehlermeldung zurück, wenn die E-Mail gegen die Richtlinie verstößt.

E-Mail des Benutzers entfernen​

Um die E-Mail des Benutzers zu entfernen, kannst du den DELETE /api/my-account/primary-email Endpunkt verwenden.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>'

Telefon verwalten​

hinweis:

Um diese Methode zu verwenden, musst du den SMS-Connector konfigurieren und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Ähnlich wie beim Aktualisieren der E-Mail kannst du den PATCH /api/my-account/primary-phone Endpunkt verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den DELETE /api/my-account/primary-phone Endpunkt, um das Telefon des Benutzers zu entfernen.

Um eine neue soziale Verbindung zu verknüpfen, solltest du zuerst eine Autorisierungs-URL mit POST /api/verifications/social anfordern.

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'
  • connectorId: Die ID des Social Connectors.
  • redirectUri: Die Redirect-URI nach der Autorisierung der Anwendung durch den Benutzer. Du solltest eine Webseite unter dieser URL hosten und den Callback erfassen.
  • state: Der State, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es handelt sich um eine zufällige Zeichenkette, die zur Verhinderung von CSRF-Angriffen verwendet wird.

In der Antwort findest du eine verificationRecordId, die du für die spätere Verwendung aufbewahrst.

Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an der redirectUri mit dem Parameter state. Dann kannst du den POST /api/verifications/social/verify Endpunkt verwenden, um die soziale Verbindung zu verifizieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

Das connectorData sind die Daten, die vom Social Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Query-Parameter von der redirectUri auf deiner Callback-Seite extrahieren und sie als JSON als Wert des Feldes connectorData übergeben.

Abschließend kannst du den POST /api/my-account/identities Endpunkt verwenden, um die soziale Verbindung zu verknüpfen.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

Soziale Verbindung entfernen​

Um eine soziale Verbindung zu entfernen, kannst du den DELETE /api/my-account/identities Endpunkt verwenden.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>'
hinweis:

Denke daran, zuerst MFA und WebAuthn zu aktivieren.

hinweis:

Um diese Methode zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Schritt 1: Ursprungs-URL deiner Frontend-App zu den Related Origins hinzufügen

WebAuthn-Passkeys sind an einen bestimmten Hostnamen gebunden, der als Relying Party ID (RP ID) bezeichnet wird. Nur Anwendungen, die auf dem Origin der RP ID gehostet werden, können mit diesen Passkeys registrieren oder authentifizieren.

Da deine Frontend-Anwendung die Account API von einer anderen Domain als die Logto-Authentifizierungsseiten aufruft, musst du Related Origins konfigurieren, um Cross-Origin-Passkey-Operationen zu ermöglichen.

Wie Logto die RP ID bestimmt:

  • Standard-Setup: Wenn du nur die Standarddomain von Logto https://[tenant-id].logto.app verwendest, ist die RP ID [tenant-id].logto.app
  • Eigene Domain: Wenn du eine eigene Domain wie https://auth.example.com konfiguriert hast, wird die RP ID zu auth.example.com

Related Origins konfigurieren:

Verwende den PATCH /api/account-center Endpunkt, um den Origin deiner Frontend-Anwendung hinzuzufügen. Wenn das Account Center deiner App z. B. unter https://account.example.com läuft:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'
hinweis:

WebAuthn unterstützt bis zu 5 eindeutige eTLD+1-Labels für Related Origins. Die eTLD+1 (effective top-level domain plus one label) ist der registrierbare Domain-Teil. Zum Beispiel:

  • https://example.com, https://app.example.com und https://auth.example.com zählen als ein Label (example.com)
  • https://shopping.com, https://shopping.co.uk und https://shopping.co.jp zählen ebenfalls als ein Label (shopping)
  • https://example.com und https://another.com zählen als zwei Labels

Wenn du mehr als 5 verschiedene Domains als Related Origins unterstützen musst, siehe die Related Origin Requests Dokumentation für Details.

Schritt 2: Neue Registrierungsoptionen anfordern

Verwende den POST /api/verifications/web-authn/registration Endpunkt, um eine Registrierung für einen neuen Passkey anzufordern. Logto erlaubt es jedem Benutzerkonto, mehrere Passkeys zu registrieren.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Du erhältst eine Antwort wie:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

Schritt 3: Passkey im lokalen Browser registrieren

Am Beispiel von @simplewebauthn/browser kannst du die Funktion startRegistration verwenden, um den Passkey im lokalen Browser zu registrieren.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // Die vom Server in Schritt 1 zurückgegebenen Daten
});
// Speichere die Antwort für die spätere Verwendung

Schritt 4: Passkey-Registrierung verifizieren

Verwende den POST /api/verifications/web-authn/registration/verify Endpunkt, um die Passkey-Registrierung zu verifizieren.

Dieser Schritt überprüft die vom Authenticator generierte kryptografische Signatur, um sicherzustellen, dass der Passkey legitim erstellt wurde und während der Übertragung nicht manipuliert wurde.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'
  • payload: Die Antwort aus dem lokalen Browser in Schritt 2.
  • verificationRecordId: Die vom Server in Schritt 1 zurückgegebene Verifizierungs-ID.

Schritt 5: Passkey verknüpfen

Abschließend kannst du den Passkey mit dem Benutzerkonto verknüpfen, indem du den POST /api/my-account/mfa-verifications Endpunkt verwendest.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'
  • type: Der Typ des MFA-Faktors, aktuell wird nur WebAuthn unterstützt.
  • newIdentifierVerificationRecordId: Die vom Server in Schritt 1 zurückgegebene Verifizierungs-ID.

Bestehende WebAuthn-Passkeys verwalten​

Um bestehende WebAuthn-Passkeys zu verwalten, kannst du den GET /api/my-account/mfa-verifications Endpunkt verwenden, um aktuelle Passkeys und andere MFA-Verifizierungsfaktoren abzurufen.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]
  • id: Die ID der Verifizierung.
  • type: Der Typ der Verifizierung, WebAuthn für WebAuthn-Passkey.
  • name: Der Name des Passkeys, optionales Feld.
  • agent: Der User-Agent des Passkeys.

Aktualisiere den Passkey-Namen mit dem PATCH /api/my-account/mfa-verifications/{verificationId}/name Endpunkt:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

Lösche den Passkey mit dem DELETE /api/my-account/mfa-verifications/{verificationId} Endpunkt:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>'
hinweis:

Denke daran, zuerst MFA und TOTP zu aktivieren.

hinweis:

Um diese Methode zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Schritt 1: TOTP-Secret generieren

Verwende den POST /api/my-account/mfa-verifications/totp-secret/generate Endpunkt, um ein TOTP-Secret zu generieren.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Die Antwort sieht beispielsweise so aus:

{
  "secret": "..."
}

Schritt 2: TOTP-Secret dem Benutzer anzeigen

Verwende das Secret, um einen QR-Code zu generieren oder zeige es dem Benutzer direkt an. Der Benutzer sollte es zu seiner Authenticator-App (wie Google Authenticator, Microsoft Authenticator oder Authy) hinzufügen.

Das URI-Format für den QR-Code sollte sein:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

Beispiel:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

Schritt 3: TOTP-Faktor binden

Nachdem der Benutzer das Secret zu seiner Authenticator-App hinzugefügt hat, muss er es verifizieren und an sein Konto binden. Verwende den POST /api/my-account/mfa-verifications Endpunkt, um den TOTP-Faktor zu binden.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'
  • type: muss Totp sein.
  • secret: Das in Schritt 1 generierte TOTP-Secret.
hinweis:

Ein Benutzer kann nur einen TOTP-Faktor gleichzeitig haben. Wenn der Benutzer bereits einen TOTP-Faktor hat, führt der Versuch, einen weiteren hinzuzufügen, zu einem 422-Fehler.

Bestehendes TOTP ersetzen​

Wenn der Benutzer bereits einen TOTP-Faktor konfiguriert hat, kannst du ihn mit einem neuen ersetzen, indem du den PUT /api/my-account/mfa-verifications/totp Endpunkt verwendest. Dies ist eine idempotente Operation, die den bestehenden TOTP entfernt und einen neuen bindet.

hinweis:

Um diese Methode zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Schritt 1: Neues TOTP-Secret generieren

Verwende den POST /api/my-account/mfa-verifications/totp-secret/generate Endpunkt, um ein neues TOTP-Secret zu generieren, und zeige es dem Benutzer wie unter Neues TOTP verknüpfen beschrieben an.

Schritt 2: TOTP-Faktor ersetzen

curl -X PUT https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"secret":"...","code":"..."}'
  • secret: Das in Schritt 1 generierte neue TOTP-Secret.
  • code: Der aus dem neuen Secret generierte TOTP-Code zur Bestätigung der Bindung.

Backup-Codes verwalten​

hinweis:

Denke daran, zuerst MFA und Backup-Codes zu aktivieren.

hinweis:

Um diese Methode zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Schritt 1: Neue Backup-Codes generieren

Verwende den POST /api/my-account/mfa-verifications/backup-codes/generate Endpunkt, um einen neuen Satz von 10 Backup-Codes zu generieren.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Die Antwort sieht beispielsweise so aus:

{
  "codes": ["...", "...", "..."]
}

Schritt 2: Backup-Codes dem Benutzer anzeigen

Bevor du die Backup-Codes an das Benutzerkonto bindest, musst du sie dem Benutzer anzeigen und ihn anweisen:

  • Lade diese Codes sofort herunter oder schreibe sie auf
  • Bewahre sie an einem sicheren Ort auf
  • Jeder Code kann nur einmal verwendet werden
  • Diese Codes sind die letzte Rettung, falls der Benutzer den Zugang zu seinen primären MFA-Methoden verliert

Du solltest die Codes in einem klaren, leicht kopierbaren Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) anbieten.

Schritt 3: Backup-Codes an das Benutzerkonto binden

Verwende den POST /api/my-account/mfa-verifications Endpunkt, um die Backup-Codes an das Benutzerkonto zu binden.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'
  • type: muss BackupCode sein.
  • codes: Das Array der im vorherigen Schritt generierten Backup-Codes.
hinweis:
  • Ein Benutzer kann nur einen Satz Backup-Codes gleichzeitig haben. Wenn alle Codes verwendet wurden, muss der Benutzer neue Codes generieren und binden.
  • Backup-Codes können nicht der einzige MFA-Faktor sein. Der Benutzer muss mindestens einen weiteren MFA-Faktor (wie WebAuthn oder TOTP) aktiviert haben.
  • Jeder Backup-Code kann nur einmal verwendet werden.

Vorhandene Backup-Codes anzeigen

Um vorhandene Backup-Codes und deren Nutzungsstatus anzuzeigen, verwende den GET /api/my-account/mfa-verifications/backup-codes Endpunkt:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}
  • code: Der Backup-Code.
  • usedAt: Der Zeitstempel, wann der Code verwendet wurde, null, wenn noch nicht verwendet.

Einstellungen für die 2-Schritt-Verifizierung verwalten​

hinweis:

Um diese Methoden zu verwenden, musst du das Feld mfa in den Account Center-Einstellungen aktivieren.

Endbenutzer können die 2-Schritt-Verifizierung für ihr Konto ein- oder ausschalten. Ein häufiger Anwendungsfall ist, wenn ein Benutzer MFA-Faktoren (wie Passkeys) konfiguriert hat, diese aber nur für die Anmeldung und nicht als zusätzlichen Verifizierungsschritt verwenden möchte — das Deaktivieren der 2-Schritt-Verifizierung ermöglicht es, die MFA-Aufforderung bei der Anmeldung zu überspringen, während die MFA-Faktoren erhalten bleiben. Dies wird durch die Einstellung skipMfaOnSignIn pro Benutzer gesteuert.

Aktuelle MFA-Einstellungen abrufen

Verwende den GET /api/my-account/mfa-settings Endpunkt, um die aktuellen Einstellungen zur 2-Schritt-Verifizierung des Benutzers abzurufen.

curl https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>'

Die Antwort sieht beispielsweise so aus:

{
  "skipMfaOnSignIn": false
}

MFA-Einstellungen aktualisieren

Um die 2-Schritt-Verifizierung zu aktivieren oder zu deaktivieren, verwende den PATCH /api/my-account/mfa-settings Endpunkt.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-settings \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"skipMfaOnSignIn":true}'
  • skipMfaOnSignIn: auf true setzen, um die 2-Schritt-Verifizierung für den Benutzer zu deaktivieren, oder auf false, um sie zu aktivieren.
hinweis:

Diese Einstellung wirkt nur, wenn die MFA-Richtlinie auf Optional gesetzt ist. Wenn MFA Verpflichtend oder Adaptiv ist, wird die Einstellung skipMfaOnSignIn ignoriert und MFA erzwungen.

Benutzersitzungen verwalten​

Aktive Sitzungen auflisten

Um die aktiven Sitzungen des Benutzers aufzulisten, kannst du den GET /api/my-account/sessions Endpunkt verwenden.

hinweis:
  • Die Berechtigung UserScope.Sessions ist erforderlich, um auf diesen Endpunkt zuzugreifen.
  • Das Feld Sitzungen in den Account Center-Einstellungen muss auf Nur Lesen oder Bearbeiten gesetzt sein.
curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Sitzung nach Sitzungs-ID widerrufen

Um eine bestimmte Sitzung zu widerrufen, verwende den DELETE /api/my-account/sessions/{sessionId} Endpunkt.

hinweis:
  • Die Berechtigung UserScope.Sessions ist erforderlich, um auf diesen Endpunkt zuzugreifen.
  • Das Feld Sitzungen in den Account Center-Einstellungen muss auf Bearbeiten gesetzt sein.
curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Optionale Query-Parameter:

  • revokeGrantsTarget: Optional kann das Ziel der Grants angegeben werden, die zusammen mit der Sitzung widerrufen werden sollen. Mögliche Werte:
    • all: Widerruft alle Grants, die mit der Sitzung verbunden sind.
    • firstParty: Widerruft nur First-Party-App-Grants, die mit der Sitzung verbunden sind. (Empfohlen für die meisten Anwendungsfälle, da der Zugriff für deine eigene App widerrufen wird, während Grants für Drittanbieter-Apps erhalten bleiben, was eine bessere Benutzererfahrung bietet.)
    • nicht angegeben: Das Standardverhalten widerruft Grants, die nicht den offline_access Scope haben, was typischerweise bedeutet, dass nicht-Refresh-Token-Grants für die Sitzung widerrufen werden.

Benutzerautorisierte Apps (Grants) verwalten​

Verwende die APIs für benutzerautorisierte Apps (Grants), wenn Benutzer autorisierte Apps auf ihrer Kontoeinstellungsseite überprüfen und widerrufen müssen.

hinweis:
  • App-Grant-APIs teilen sich das gleiche Berechtigungsmodell wie Sitzungs-APIs.
  • Die Berechtigung UserScope.Sessions ist erforderlich.
  • Das Feld Sitzungen in den Account Center-Einstellungen muss aktiviert sein:
    • Nur Lesen oder Bearbeiten, um Grants aufzulisten.
    • Bearbeiten, um Grants zu widerrufen.

Aktive App-Grants auflisten

Um die aktiven App-Grants des aktuellen Benutzers aufzulisten, verwende den GET /api/my-account/grants Endpunkt.

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Optionaler Query-Parameter:

  • appType=firstParty: Gibt nur First-Party-App-Grants zurück.
  • appType=thirdParty: Gibt nur Third-Party-App-Grants zurück.
  • Ohne appType: Gibt alle aktiven Grants zurück.
curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

App-Grant nach Grant-ID widerrufen

Um einen bestimmten App-Grant zu widerrufen, verwende den DELETE /api/my-account/grants/{grantId} Endpunkt.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

Wenn ein Grant widerrufen wird, werden zuvor ausgestellte opake Zugangstokens (Opaque tokens) und Auffrischungstokens (Refresh tokens) für diesen Grant ungültig.