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 den Umweg über die Management API gehen 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 dass die Management API zwischengeschaltet werden muss.
- 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 jetzt 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 alsBearer <access_token>
hinzu.
Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig in Logto integriert ist.
Einige häufige Anwendungsfälle sind unten aufgeführt:
- Benutzerprofil abrufen
- Benutzerprofil aktualisieren
- Benutzerpasswort aktualisieren
- Benutzeridentitäten einschließlich E-Mail, Telefon und sozialer Verbindungen aktualisieren
- MFA-Faktoren (Verifizierungen) verwalten
Um mehr über die verfügbaren APIs zu erfahren, besuche bitte die Logto Account API Referenz und die Logto Verification API Referenz.
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 > Kontozentrale.
Die Account API ist standardmäßig deaktiviert, daher sind ihre Zugriffskontrollen gesperrt. Aktiviere Account API aktivieren, um sie einzuschalten.
Nach der Aktivierung kannst du die Berechtigungen pro Feld für Identifikatoren, Profildaten und Drittanbieter-Token-Zugriff konfigurieren. Jedes Feld unterstützt Off
, ReadOnly
oder Edit
; der Standardwert ist Off
.
- Sicherheitsfelder:
- Zu den Feldern gehören: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort und MFA.
- Bevor Endbenutzer diese Felder bearbeiten, müssen sie ihre Identität per Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungsdatensatz-ID zu erhalten. Siehe Verifizierungsdatensatz-ID erhalten.
- Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu WebAuthn Related Origins hinzu, damit Kontozentrale und Anmeldungserlebnis Passkeys teilen können. Siehe Neuen WebAuthn-Passkey verknüpfen.
- Profilfelder:
- Zu den Feldern gehören: Benutzername, Name, Avatar, Profil (weitere Standard-Profilattribute) und benutzerdefinierte Daten.
- Endbenutzer können diese ohne zusätzliche Verifizierung bearbeiten.
- Secret Vault: Für OIDC- oder OAuth-Sozial- und Enterprise-Connectors speichert der Logto Secret Vault Drittanbieter-Zugangs- und Auffrischungstokens nach der Authentifizierung sicher. Apps können dann externe APIs aufrufen, wie z. B. das Synchronisieren von Google-Kalender-Ereignissen, ohne die Benutzer erneut zur Anmeldung aufzufordern. Die Token-Abfrage ist automatisch verfügbar, sobald die Account API aktiviert ist.
Wie greife ich auf die Account API zu
Um sicherzustellen, dass das Zugangstoken (Access token) die entsprechenden Berechtigungen hat, stelle sicher, dass du die entsprechenden Berechtigungen (Scopes) in deiner Logto-Konfiguration richtig eingerichtet hast.
Zum Beispiel musst du für die POST /api/my-account/primary-email
API die Berechtigung (Scope) email
konfigurieren; für die POST /api/my-account/primary-phone
API die Berechtigung (Scope) phone
.
import { type LogtoConfig, UserScope } from '@logto/js';
const config: LogtoConfig = {
// ...andere Optionen
// Füge die passenden Berechtigungen (Scopes) 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 Adressen zu verwalten
UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs
UserScope.Profile, // Um Benutzerprofile zu verwalten
],
};
Zugangstoken (Access token) 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
-Feld für die Zugangstoken-Anfrage an /oidc/token
leer lassen.
Zugriff auf die Account API mit Zugangstoken (Access token)
Du solltest das Zugangstoken (Access token) im Authorization
-Feld 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 Einstellungen der Kontozentrale variieren.
Grundlegende Kontoinformationen aktualisieren
Zu den grundlegenden Kontoinformationen gehören 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 wie familyName, givenName, middleName, nickname, profile (Profilseiten-URL), website, gender, birthdate, zoneinfo, locale und address zu aktualisieren, 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 erfordert die Account API eine zusätzliche Autorisierungsebene für Vorgänge, die Identifikatoren und andere sensible Informationen betreffen.
Verifizierungsdatensatz-ID erhalten
Zuerst musst du eine Verifizierungsdatensatz-ID mit einer Gültigkeit von 10 Minuten (TTL) erhalten. Diese kann verwendet werden, um die Identität des Benutzers zu verifizieren, bevor sensible Informationen aktualisiert werden. Das bedeutet, sobald ein Benutzer seine Identität erfolgreich per Passwort, E-Mail-Verifizierungscode oder SMS-Verifizierungscode bestätigt hat, hat er 10 Minuten Zeit, um seine authentifizierungsbezogenen Daten zu aktualisieren, einschließlich Identifikatoren, Zugangsdaten, Social-Account-Verknüpfung und MFA.
Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du das Benutzerpasswort verifizieren oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden.
Passwort des Benutzers verifizieren
curl -X POST https://[tenant-id].logto.app/api/verifications/password \
-H 'authorization: Bearer <access_token>' \
-H 'content-type: application/json' \
--data-raw '{"password":"..."}'
Die Antwort sieht beispielsweise so aus:
{
"verificationRecordId": "...",
"expiresAt": "..."
}
Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden
Um diese Methode zu verwenden, musst du den E-Mail-Connector konfigurieren oder den SMS-Connector konfigurieren und sicherstellen, dass die UserPermissionValidation
-Vorlage konfiguriert ist.
Am Beispiel E-Mail: Fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID:
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":"..."}}'
Die Antwort sieht beispielsweise so aus:
{
"verificationRecordId": "...",
"expiresAt": "..."
}
Nach Erhalt des Verifizierungscodes kannst du ihn verwenden, um den Verifizierungsstatus des Verifizierungsdatensatzes zu aktualisieren.
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":"123456"}'
Nach der Verifizierung des Codes kannst du nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.
Um mehr über Verifizierungen zu erfahren, siehe Sicherheitsverifizierung über die Account API.
Anfrage mit Verifizierungsdatensatz-ID senden
Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungsdatensatz-ID im Anfrage-Header mit dem Feld logto-verification-id
angeben.
Passwort des Benutzers aktualisieren
Um das Passwort des Benutzers 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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"password":"..."}'
Neue E-Mail aktualisieren oder verknüpfen
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. Verwende diesen, um die E-Mail zu verifizieren.
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 Anfragekörper als newIdentifierVerificationRecordId
.
curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'
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>' \
-H 'logto-verification-id: <verification_record_id>'
Telefon verwalten
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.
Neue soziale Verbindung verknüpfen
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 Weiterleitungs-URL nach der Autorisierung durch den Benutzer. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen.state
: Der State, der nach der Autorisierung durch den Benutzer zurückgegeben wird. Es handelt sich um einen zufälligen String, der zur Verhinderung von CSRF-Angriffen verwendet wird.
In der Antwort findest du eine verificationRecordId
, die du für später aufbewahren solltest.
Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an die 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
ist die von dem Social Connector nach der Autorisierung des Benutzers zurückgegebene Daten. Du musst die Query-Parameter aus der redirectUri
auf deiner Callback-Seite extrahieren und sie als JSON im Feld 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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"newIdentifierVerificationRecordId":"..."}'
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>' \
-H 'logto-verification-id: <verification_record_id>'
Neuen WebAuthn-Passkey verknüpfen
Denke daran, zuerst MFA und WebAuthn zu aktivieren.
Um diese Methode zu verwenden, musst du das Feld mfa
in den Einstellungen der Kontozentrale 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 diese 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 zuauth.example.com
Related Origins konfigurieren:
Verwende den PATCH /api/account-center
Endpunkt, um den Origin deiner Frontend-Anwendung hinzuzufügen. Wenn deine App beispielsweise 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"]}'
Um mehr über Related Origins zu erfahren, siehe die Related Origin Requests Dokumentation.
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 jedem Benutzerkonto die Registrierung mehrerer Passkeys.
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.
In diesem Schritt wird die vom Authenticator generierte kryptografische Signatur überprüft, 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 Verifizierungsdatensatz-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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'
verification_record_id
: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Siehe Verifizierungsdatensatz-ID erhalten für Details.type
: Der Typ des MFA-Faktors, aktuell wird nurWebAuthn
unterstützt.newIdentifierVerificationRecordId
: Die vom Server in Schritt 1 zurückgegebene Verifizierungsdatensatz-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.
Den Passkey-Namen kannst du mit dem PATCH /api/my-account/mfa-verifications/{verificationId}/name
Endpunkt aktualisieren:
curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"name":"..."}'
Den Passkey kannst du mit dem DELETE /api/my-account/mfa-verifications/{verificationId}
Endpunkt löschen:
curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>'
Neues TOTP verknüpfen
Denke daran, zuerst MFA und TOTP zu aktivieren.
Um diese Methode zu verwenden, musst du das Feld mfa
in den Einstellungen der Kontozentrale 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 in 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:[email protected]?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 dazu den POST /api/my-account/mfa-verifications
Endpunkt.
curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
-H 'authorization: Bearer <access_token>' \
-H 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"type":"Totp","secret":"..."}'
verification_record_id
: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Siehe Verifizierungsdatensatz-ID erhalten für Details.type
: MussTotp
sein.secret
: Das in Schritt 1 generierte TOTP-Secret.
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.
Backup-Codes verwalten
Denke daran, zuerst MFA und Backup-Codes zu aktivieren.
Um diese Methode zu verwenden, musst du das Feld mfa
in den Einstellungen der Kontozentrale 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 die Backup-Codes an das Benutzerkonto gebunden werden, 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 Zugriff auf seine primären MFA-Methoden verliert
Du solltest die Codes in einem klaren, einfach zu kopierenden 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 'logto-verification-id: <verification_record_id>' \
-H 'content-type: application/json' \
--data-raw '{"type":"BackupCode","codes":["...","...","..."]}'
verification_record_id
: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Siehe Verifizierungsdatensatz-ID erhalten für Details.type
: MussBackupCode
sein.codes
: Das Array der im vorherigen Schritt generierten Backup-Codes.
- Ein Benutzer kann immer 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 Zeitpunkt, zu dem der Code verwendet wurde,null
, wenn noch nicht verwendet.