Zum Hauptinhalt springen

Kontoeinstellungen durch Account API

Was ist die Logto Account API​

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

  • Direkter Zugang: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto zuzugreifen und es zu verwalten, ohne die Weiterleitung über die Management API.
  • 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 kommen bald.
  • Globale Zugangskontrolle: Der Administrator hat volle, globale Kontrolle über die Zugangseinstellungen und kann jedes Feld anpassen.
  • Nahtlose Autorisierung: Die Autorisierung ist einfacher denn je! Verwenden Sie einfach client.getAccessToken(), um ein opakes Zugangstoken für OP (Logto) zu erhalten, und fügen Sie es dem Authorization-Header als Bearer <access_token> hinzu.

Mit der Logto Account API können Sie ein benutzerdefiniertes Kontoverwaltungssystem wie eine Profilseite erstellen, die vollständig in Logto integriert ist.

Einige häufige Verwendungen sind unten aufgeführt:

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

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

hinweis:

Spezielle Account APIs für die folgenden Einstellungen kommen bald: MFA, SSO, Benutzerdefinierte Daten (Benutzer) und Kontolöschung. In der Zwischenzeit können Sie diese Funktionen mit den Logto Management APIs implementieren. Siehe Kontoeinstellungen über die Management API für weitere Details.

Wie man die Account API aktiviert​

Standardmäßig ist die Account API deaktiviert. Um sie zu aktivieren, müssen Sie 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. Sie können 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 Feld enabled wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das Feld fields 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 Benutzernamenfeld.
  • 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.

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

Wie man auf die Account API zugreift​

Ein Zugangstoken abrufen​

Nachdem Sie das SDK in Ihrer Anwendung eingerichtet haben, können Sie 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 Sie das offizielle SDK nicht verwenden, sollten Sie das resource für die Zugangstoken-Anfrage an /oidc/token leer lassen.

Zugriff auf die Account API mit Zugangstoken​

Sie sollten das Zugangstoken im Authorization-Feld der HTTP-Header im Bearer-Format (Bearer YOUR_TOKEN) platzieren, wenn Sie mit der Account API interagieren.

Ein Beispiel, um die Benutzerkontoinformationen abzurufen:

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

Verwaltung grundlegender Kontoinformationen​

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, können Sie 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, können Sie 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":"..."}'

Verwaltung von Identifikatoren und anderen sensiblen Informationen​

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 müssen Sie 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, können Sie 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, müssen Sie den E-Mail-Connector konfigurieren oder den SMS-Connector konfigurieren, und sicherstellen, dass die UserPermissionValidation-Vorlage konfiguriert ist.

Nehmen wir E-Mail als Beispiel, fordern Sie einen neuen Verifizierungscode an und erhalten Sie 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 können Sie 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 können Sie nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren.

Anfrage mit Verifizierungsdatensatz-ID senden​

Wenn Sie eine Anfrage senden, um den Identifikator des Benutzers zu aktualisieren, müssen Sie die Verifizierungsdatensatz-ID dem Anfrage-Header mit dem Feld logto-verification-id anhängen.

hinweis:

Um diese Methode zu verwenden, müssen Sie den E-Mail-Connector konfigurieren, und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, sollten Sie zuerst das Eigentum der E-Mail nachweisen.

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

Sie finden eine verificationId in der Antwort und erhalten einen Verifizierungscode in der E-Mail, verwenden Sie 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 können Sie nun die E-Mail des Benutzers aktualisieren, setzen Sie 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":"..."}'

Die E-Mail des Benutzers entfernen​

Um die E-Mail des Benutzers zu entfernen, können Sie 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, müssen Sie den SMS-Connector konfigurieren, und sicherstellen, dass die BindNewIdentifier-Vorlage konfiguriert ist.

Ähnlich wie beim Aktualisieren der E-Mail können Sie 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.

Um eine neue soziale Verbindung zu verknüpfen, sollten Sie 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. Sie sollten 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 finden Sie eine verificationRecordId, bewahren Sie sie für die spätere Verwendung auf.

Nachdem der Benutzer die Anwendung autorisiert hat, erhalten Sie einen Callback an der redirectUri mit dem state-Parameter. Dann können Sie 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. Sie müssen die Abfrageparameter von der redirectUri auf Ihrer Callback-Seite analysieren und als JSON als Wert des connectorData-Feldes verpacken.

Schließlich können Sie den Endpunkt POST /api/my-account/identities 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":"..."}'

Eine soziale Verbindung entfernen​

Um eine soziale Verbindung zu entfernen, können Sie 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>'