Kontoeinstellungen über die Account API

Was ist die Logto Account API

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

• Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto zuzugreifen und es zu verwalten, ohne die Weiterleitung der Management API zu benötigen.
• Benutzerprofil- und Identitätsverwaltung: 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 kommen bald.
• Globale Zugriffskontrolle: Der Administrator hat vollständige, globale Kontrolle über die Zugriffseinstellungen und kann jedes Feld anpassen.
• Nahtlose Autorisierung: Die Autorisierung ist einfacher denn je! Verwende einfach client.getAccessToken(), um ein opakes Zugangstoken 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 benutzerdefiniertes Kontoverwaltungssystem wie eine Profilseite erstellen, die vollständig in Logto integriert ist.

Einige häufige Anwendungen sind unten aufgeführt:

• Benutzerprofil abrufen
• Benutzerprofil aktualisieren
• Benutzerpasswort aktualisieren
• Benutzeridentitäten einschließlich E-Mail, Telefon und sozialer Verbindungen aktualisieren

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

Wie man die Account API aktiviert

Standardmäßig ist die Account API deaktiviert. Um sie zu aktivieren, musst du die Management API verwenden, um die globalen Einstellungen zu aktualisieren.

Der API-Endpunkt /api/account-center kann verwendet werden, um die Einstellungen des Account Centers abzurufen und zu aktualisieren. Du kannst ihn verwenden, um die Account API zu aktivieren oder zu deaktivieren und die Felder anzupassen.

Beispielanfrage:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

Das enabled-Feld wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das fields-Feld wird verwendet, um die Felder anzupassen. Der Wert kann Off, Edit, ReadOnly sein. Der Standardwert ist Off. Die Liste der Felder:

• name: Das Namensfeld.
• avatar: Das Avatar-Feld.
• profile: Das Profilfeld, einschließlich seiner Unterfelder.
• username: Das Benutzername-Feld.
• email: Das E-Mail-Feld.
• phone: Das Telefonfeld.
• password: Das Passwortfeld, beim Abrufen wird true zurückgegeben, wenn der Benutzer ein Passwort gesetzt hat, andernfalls false.
• social: Soziale Verbindungen.

Erfahre mehr über die API-Details in der Logto Management API Referenz.

Wie man auf die Account API zugreift

Ein Zugangstoken abrufen

Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode client.getAccessToken() verwenden, um ein Zugangstoken abzurufen. Dieses Token ist ein opakes Token, das zum Zugriff auf die Account API verwendet werden kann.

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

Zugriff auf die Account API mit Zugangstoken

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

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

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

Der Antwortkörper könnte folgendermaßen aussehen:

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

Die Antwortfelder können je nach den Einstellungen des Account Centers variieren.

Grundlegende Kontoinformationen aktualisieren

Grundlegende Kontoinformationen umfassen den Benutzernamen, den Namen, das Avatar und das Profil.

Um Benutzernamen, Namen und Avatar zu aktualisieren, kannst du den Endpunkt PATCH /api/my-account 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 das Profil zu aktualisieren, kannst du den Endpunkt PATCH /api/my-account/profile 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 weitere Autorisierungsebene für die Vorgänge, die Identifikatoren und andere sensible Informationen betreffen.

Eine Verifizierungsdatensatz-ID erhalten

Zuerst musst du eine Verifizierungsdatensatz-ID erhalten, die verwendet werden kann, um die Identität des Benutzers beim Aktualisieren von Identifikatoren zu überprüfen.

Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du das Passwort des Benutzers überprüfen oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden.

Das Passwort des Benutzers überprüfen

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

Der Antwortkörper könnte folgendermaßen aussehen:

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

Überprüfung durch Senden eines Verifizierungscodes an die E-Mail oder das Telefon des Benutzers

hinweis

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

Nehmen wir E-Mail als Beispiel, 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":"..."}}'

Der Antwortkörper könnte folgendermaßen aussehen:

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

Nach Erhalt des Verifizierungscodes kannst du ihn verwenden, um den Verifizierungsstatus des Verifizierungsdatensatzes zu aktualisieren.

curl -X PATCH 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 Überprüfung des Codes kannst du nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.

Anfrage mit Verifizierungsdatensatz-ID senden

Beim Senden einer Anfrage zur Aktualisierung des Identifikators des Benutzers musst du die Verifizierungsdatensatz-ID an den Anfrage-Header mit dem Feld logto-verification-id anhängen.

Neue E-Mail aktualisieren oder verknüpfen

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, solltest du zuerst das Eigentum der E-Mail nachweisen.

Rufe den Endpunkt POST /api/verifications/verification-code 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 wirst eine verificationId in der Antwort finden und einen Verifizierungscode in der E-Mail erhalten, verwende ihn, um die E-Mail zu überprüfen.

curl -X PATCH 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 Überprüfung des Codes kannst du nun die E-Mail des Benutzers aktualisieren, setze die verificationId in den Anfragekörper als newIdentifierVerificationRecordId.

curl -X PATCH 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 Endpunkt DELETE /api/my-account/primary-email 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

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 Endpunkt PATCH /api/my-account/primary-phone verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den Endpunkt DELETE /api/my-account/primary-phone, 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 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 sozialen Connectors.
• redirectUri: Die Umleitungs-URI, nachdem der Benutzer die Anwendung autorisiert hat. Du solltest eine Webseite unter dieser URL hosten und den Callback erfassen.
• state: Der Zustand, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es ist eine zufällige Zeichenfolge, die verwendet wird, um CSRF-Angriffe zu verhindern.

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

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

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":"..."}'

Die connectorData sind die Daten, die vom sozialen Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Abfrageparameter von der redirectUri auf deiner Callback-Seite analysieren und als JSON als Wert des connectorData-Feldes umwickeln.

Schließlich kannst du den Endpunkt PATCH /api/my-account/identities verwenden, um die soziale Verbindung zu verknüpfen.

curl -X PATCH 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":"..."}'

Eine soziale Verbindung entfernen

Um eine soziale Verbindung zu entfernen, kannst du den Endpunkt DELETE /api/my-account/identities 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>'