Drittanbieter-Token-Speicherung & API-Zugriff

Das Drittanbieter-Token-Set (auch bekannt als föderiertes Token-Set) ist ein Geheimnistyp, der im Secret Vault von Logto gespeichert wird, um Zugangstokens (Zugangstoken (Access token)) und Auffrischungstokens (Auffrischungstoken (Refresh token)), die von Drittanbieter-Identitätsanbietern ausgestellt wurden, sicher zu verwalten. Wenn sich ein Benutzer über einen Social- oder Enterprise SSO-Connector authentifiziert, speichert Logto die ausgestellten Tokens im Vault. Diese Tokens können später abgerufen werden, um im Namen des Benutzers auf Drittanbieter-APIs zuzugreifen, ohne dass eine erneute Authentifizierung erforderlich ist.

Häufige Anwendungsfälle

Diese Fähigkeit ist essenziell für moderne Anwendungen wie KI-Agenten, SaaS-Plattformen, Produktivitätstools und Kundenanwendungen, die im Namen der Benutzer mit Drittanbieterdiensten interagieren müssen. Hier einige praktische Beispiele:

📅 Kalenderverwaltungs-Apps: Nachdem sich ein Benutzer mit Google anmeldet, kann deine Produktivitäts-App automatisch seine Kalendereinträge synchronisieren, neue Meetings erstellen und Einladungen versenden, ohne erneut nach einer Authentifizierung zu fragen.

🤖 KI-Assistenten: Ein KI-Agent kann auf die GitHub-Repositories eines Benutzers zugreifen, um Code zu analysieren, Pull Requests zu erstellen oder Issues zu verwalten. Alles mit der einmaligen Zustimmung des Benutzers während der Anmeldung oder Kontoverknüpfung.

📊 Analyse-Dashboards: SaaS-Plattformen können Daten aus den verbundenen Social-Media-Konten der Benutzer (Facebook, LinkedIn) abrufen, um Einblicke und Berichte zu generieren, ohne den Arbeitsablauf durch wiederholte Login-Aufforderungen zu unterbrechen.

Drittanbieter-Token-Speicherung aktivieren

Diese Funktion ist für Social Connectors verfügbar, die die Token-Speicherung unterstützen. Drittanbieter-Tokens können während der sozialen Anmeldung, sozialen Kontoverknüpfung und beim Erneuern von Tokens für Drittanbieter-API-Zugriff gespeichert werden. Aktuell unterstützte Connectors sind: GitHub, Google, Facebook, Standard OAuth 2.0 und Standard OIDC. Die Unterstützung für weitere Connectors wird schrittweise eingeführt.

Navigiere zu Konsole > Connectors > Social Connectors.
Wähle den Social Connector aus, für den du die Drittanbieter-Token-Speicherung aktivieren möchtest.
Folge den Einrichtungsanleitungen, um den Connector zu konfigurieren, einschließlich der Hinzufügung der erforderlichen Berechtigungen (Scopes), um auf bestimmte Drittanbieter-APIs zuzugreifen.
Aktiviere auf der Seite „Einstellungen“ die Option Tokens für dauerhaften API-Zugriff speichern.

Enterprise SSO Connectors

Die Token-Speicherung ist für alle OIDC Enterprise Connectors verfügbar. Zugangstokens (Zugangstoken (Access token)) und Auffrischungstokens (Auffrischungstoken (Refresh token)) können während des Enterprise Single Sign-On gespeichert werden. Aktuell unterstützte Connectors sind: Google Workspace, Microsoft Entra ID (OIDC), Okta und OIDC (Enterprise).

Navigiere zu Konsole > Enterprise SSO.
Wähle den Enterprise SSO Connector aus, für den du die Drittanbieter-Token-Speicherung aktivieren möchtest.
Folge den Einrichtungsanleitungen, um den Connector zu konfigurieren, einschließlich der Hinzufügung der erforderlichen Berechtigungen (Scopes), um auf bestimmte Drittanbieter-APIs zuzugreifen.
Aktiviere im Tab „SSO-Erfahrung“ die Option Tokens für dauerhaften API-Zugriff speichern.

Stelle sicher, dass du deine Änderungen speicherst.

Token-Speicherung

Sobald die Drittanbieter-Token-Speicherung aktiviert ist, speichert Logto automatisch die Zugangstokens (Zugangstoken (Access token)) und Auffrischungstokens (Auffrischungstoken (Refresh token)), die vom föderierten Identitätsanbieter ausgestellt wurden, wann immer sich ein Benutzer über einen Social- oder Enterprise SSO-Connector authentifiziert. Dies umfasst:

Die gespeicherten Tokens sind mit der Social- oder Enterprise SSO-Identität des Benutzers verknüpft, sodass sie später für den API-Zugriff abgerufen werden können, ohne dass eine erneute Authentifizierung erforderlich ist.

Überprüfung des Token-Speicherstatus

Du kannst den Drittanbieter-Token-Speicherstatus eines Benutzers in der Logto-Konsole überprüfen:

Navigiere zu Konsole > Benutzer.
Klicke auf den Benutzer, den du überprüfen möchtest. Dies führt dich zur Detailseite des Benutzers.
Scrolle zum Abschnitt Verbindungen. Dieser Bereich listet alle Social- und Enterprise SSO-Verbindungen auf, die mit dem Benutzer verknüpft sind.
Jeder Eintrag zeigt ein Token-Status-Label, das angibt, ob Tokens für diese Verbindung gespeichert sind.
Klicke auf den Verbindungseintrag, um weitere Details anzuzeigen, einschließlich der gespeicherten Zugangstoken-Metadaten und der Verfügbarkeit eines Auffrischungstokens (falls vorhanden).

Du kannst auch die Drittanbieter-Identitäten und den Token-Speicherstatus eines Benutzers über die Management API überprüfen:

GET /api/users/{userId}/identities/{target}?includeTokenSecret=true: Ruft die Social-Identität eines Benutzers und den damit verbundenen Token-Speicherstatus für einen bestimmten Connector-Target (z. B. github, google usw.) ab.
GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true: Ruft die Enterprise SSO-Identität eines Benutzers und den damit verbundenen Token-Speicherstatus für eine bestimmte SSO-Connector-ID ab.

Token-Speicherstatus

Aktiv: Das Zugangstoken (Zugangstoken (Access token)) ist gespeichert und aktiv.
Abgelaufen: Das Zugangstoken (Zugangstoken (Access token)) ist gespeichert, aber abgelaufen. Wenn ein Auffrischungstoken (Auffrischungstoken (Refresh token)) verfügbar ist, kann damit ein neues Zugangstoken (Zugangstoken (Access token)) abgerufen werden.
Inaktiv: Für diese Verbindung ist kein Zugangstoken (Zugangstoken (Access token)) gespeichert. Dies kann passieren, wenn der Benutzer sich nicht über diese Verbindung authentifiziert hat oder die Token-Speicherung gelöscht wurde.
Nicht anwendbar: Der Connector unterstützt keine Token-Speicherung.

Token-Metadaten

Aus Gründen der Datenintegrität und Sicherheit werden alle Tokens vor der Speicherung im Secret Vault verschlüsselt. Die tatsächlichen Token-Werte sind nur für den Endbenutzer mit entsprechender Autorisierung zugänglich. Entwickler können hingegen nur die Metadaten des Token-Sets abrufen, um den Status der gespeicherten Tokens zu verstehen, ohne sensible Inhalte offenzulegen.

createdAt: Der Zeitstempel, zu dem die Verbindung erstmals hergestellt und das Token-Set initial im Secret Vault gespeichert wurde.
updatedAt: Der Zeitpunkt der letzten Aktualisierung des Token-Sets.
- Wenn kein Auffrischungstoken (Auffrischungstoken (Refresh token)) verfügbar ist, entspricht dieser Wert createdAt.
- Wenn ein Auffrischungstoken (Auffrischungstoken (Refresh token)) vorhanden ist, spiegelt dieser Wert den letzten Zeitpunkt wider, zu dem das Zugangstoken (Zugangstoken (Access token)) erneuert wurde.
hasRefreshToken: Gibt an, ob ein Auffrischungstoken (Auffrischungstoken (Refresh token)) verfügbar ist. Wenn der Connector Offline-Zugriff unterstützt und die Autorisierungsanfrage entsprechend konfiguriert ist, speichert Logto das Auffrischungstoken (Auffrischungstoken (Refresh token)), wenn es vom Identitätsanbieter zusammen mit dem Zugangstoken (Zugangstoken (Access token)) ausgestellt wird. Wenn das Zugangstoken (Zugangstoken (Access token)) abläuft und ein gültiges Auffrischungstoken (Auffrischungstoken (Refresh token)) existiert, versucht Logto automatisch, ein neues Zugangstoken (Zugangstoken (Access token)) mit dem gespeicherten Auffrischungstoken (Auffrischungstoken (Refresh token)) zu erhalten, wann immer der Benutzer Zugriff auf den verbundenen Anbieter anfordert.
expiresAt: Die geschätzte Ablaufzeit des Zugangstokens (Zugangstoken (Access token)) in Sekunden. Dies wird basierend auf dem expires_in-Wert berechnet, der vom Token-Endpunkt des Identitätsanbieters zurückgegeben wird. (Dieses Feld ist nur verfügbar, wenn der Anbieter expires_in in der Token-Antwort enthält.)
scope: Die Berechtigung (Scope) des Zugangstokens (Zugangstoken (Access token)), die die vom Identitätsanbieter gewährten Berechtigungen angibt. Dies ist nützlich, um zu verstehen, welche Aktionen mit dem gespeicherten Zugangstoken (Zugangstoken (Access token)) durchgeführt werden können. (Dieses Feld ist nur verfügbar, wenn der Anbieter scope in der Token-Antwort enthält.)
tokenType: Der Typ des Zugangstokens (Zugangstoken (Access token)), typischerweise "Bearer". (Dieses Feld ist nur verfügbar, wenn der Anbieter token_type in der Token-Antwort enthält.)

Token-Abruf

Sobald die Token-Speicherung aktiviert und Tokens sicher im Secret Vault von Logto gespeichert sind, können Endbenutzer ihre Drittanbieter-Zugangstokens (Zugangstoken (Access token)) aus deiner Client-Anwendung abrufen, indem sie die User Account API von Logto integrieren.

GET /my-account/identities/:target/access-token: Ruft das Zugangstoken (Zugangstoken (Access token)) für eine Social-Identität ab, indem der Connector-Target angegeben wird (z. B. github, google).
GET /my-account/sso-identities/:connectorId/access-token: Ruft das Zugangstoken (Zugangstoken (Access token)) für eine Enterprise SSO-Identität ab, indem die Connector-ID angegeben wird.

info:

Um Drittanbieter-Zugangstokens (Zugangstoken (Access token)) abzurufen, musst du zuerst die Account API für Endbenutzer unter Konsole > Anmeldung & Konto > Account Center aktivieren. Erfahre, wie du die Account API aktivierst und sie mit einem von Logto ausgestellten Zugangstoken (Zugangstoken (Access token)) aufrufst.

Token-Rotation

Die Endpunkte zum Token-Abruf liefern:

200 OK: Wenn das Zugangstoken (Zugangstoken (Access token)) erfolgreich abgerufen wurde und noch gültig ist.
404 Nicht gefunden: Wenn der Benutzer keine Social- oder Enterprise SSO-Identität mit dem angegebenen Target oder der Connector-ID hat oder wenn das Zugangstoken (Zugangstoken (Access token)) nicht gespeichert ist.
401 Nicht autorisiert: Wenn das Zugangstoken (Zugangstoken (Access token)) abgelaufen ist.

Wenn das Zugangstoken (Zugangstoken (Access token)) abgelaufen ist und ein Auffrischungstoken (Auffrischungstoken (Refresh token)) verfügbar ist, versucht Logto automatisch, das Zugangstoken (Zugangstoken (Access token)) zu erneuern und gibt das neue Zugangstoken (Zugangstoken (Access token)) in der Antwort zurück. Die Token-Speicherung im Secret Vault wird ebenfalls mit dem neuen Zugangstoken (Zugangstoken (Access token)) und den zugehörigen Metadaten aktualisiert.

Token-Speicherung löschen

Die Drittanbieter-Token-Speicherung ist direkt mit den Social- oder Enterprise SSO-Verbindungen jedes Benutzers verknüpft. Das bedeutet, dass das gespeicherte Token-Set in folgenden Fällen automatisch gelöscht wird:

Die zugehörige Social- oder Enterprise SSO-Identität wird aus dem Benutzerkonto entfernt.
Das Benutzerkonto wird aus deinem Mandanten gelöscht.
Der Social- oder Enterprise SSO-Connector wird aus deinem Mandanten gelöscht.

Tokens widerrufen

Du kannst das Drittanbieter-Token-Set eines Benutzers auch manuell löschen, um den Zugriff zu widerrufen:

Über die Konsole: Navigiere zur Identitätsdetailseite des Benutzers. Scrolle zum Abschnitt Zugangstoken (Zugangstoken (Access token)) (falls Token-Speicherung verfügbar ist) und klicke am Ende des Abschnitts auf die Schaltfläche Tokens löschen.
Über die Management API:
- DELETE /api/secret/:id: Löscht ein bestimmtes Geheimnis anhand seiner ID, die du aus den Identitätsdetails des Benutzers erhältst.

Das Widerrufen des Token-Sets zwingt den Benutzer, sich erneut beim Drittanbieter zu authentifizieren, um ein neues Zugangstoken (Zugangstoken (Access token)) zu erhalten, bevor er wieder auf Drittanbieter-APIs zugreifen kann.

Reauthentifizierung und Token-Erneuerung

In Szenarien, in denen ein gespeichertes Zugangstoken (Zugangstoken (Access token)) abgelaufen ist oder eine Anwendung zusätzliche API-Berechtigungen (Scopes) anfordern muss, können Endbenutzer sich beim Drittanbieter erneut authentifizieren, um ein neues Zugangstoken (Zugangstoken (Access token)) zu erhalten – ohne sich erneut bei Logto anmelden zu müssen. Dies kann über die Social Verification API von Logto erfolgen, die es Benutzern ermöglicht, einen föderierten Social-Autorisierungsfluss erneut zu starten und ihr gespeichertes Token-Set zu aktualisieren.

hinweis:

Das erneute Initiieren der föderierten Autorisierung ist derzeit auf Social Connectors beschränkt. Für Enterprise SSO Connectors erfordern Reauthentifizierung und Token-Erneuerung, dass der Benutzer erneut einen vollständigen Logto-Authentifizierungsfluss durchläuft, da eine direkte Reautorisierung mit dem Enterprise SSO-Anbieter nach der Anmeldung derzeit nicht unterstützt wird.

Der Benutzer startet eine Social Verification-Anfrage, indem er den Endpunkt POST /api/verification/social aufruft. Der Benutzer kann benutzerdefinierte Berechtigungen (Scopes) angeben, um zusätzliche Berechtigungen vom Drittanbieter anzufordern.
```
curl -X POST https://<your-logto-domain>/api/verification/social \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "<state>",
    "connectorId": "<logto_connectorId>",
    "redirectUri": "<redirect_uri>",
    "scope": "<custom_scope>"
  }'
```
- authorization header: Das vom Logto ausgestellte Zugangstoken (Zugangstoken (Access token)) des Benutzers.
- connectorId: Die Social Connector ID in Logto.
- redirectUri: Die URI, zu der der Benutzer nach der Authentifizierung zurück zu deiner Anwendung geleitet wird. Diese URI muss in den Anwendungseinstellungen des Anbieters registriert werden.
- scope: (Optional) Benutzerdefinierte Berechtigungen (Scopes), um zusätzliche Berechtigungen vom Drittanbieter anzufordern. Wenn nicht angegeben, werden die in der Connector-Konfiguration hinterlegten Standard-Berechtigungen verwendet.
Logto erstellt einen neuen Social Verification-Datensatz und gibt die Social Verification ID zusammen mit der Autorisierungs-URL zurück, um den Benutzer zum Drittanbieter zur Authentifizierung weiterzuleiten.

Die Antwort sieht wie folgt aus:
```
{
  "verificationRecordId": "<social_verification_id>",
  "authorizationUri": "<authorization_url>",
  "expiresAt": "<expiration_time>"
}
```
Leite den Benutzer zur Autorisierungs-URL weiter. Der Benutzer authentifiziert sich beim Drittanbieter und erteilt die Berechtigungen.
Der Drittanbieter leitet den Benutzer mit einem Autorisierungscode zurück zu deiner Client-Anwendung.
Verarbeite den Autorisierungs-Callback, indem du den Autorisierungscode an den Verification-Endpunkt von Logto weiterleitest:
```
curl -X POST https://<your-logto-domain>/api/verification/social/verify \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "verificationRecordId": "<social_verification_id>",
    "connectorData": {
      "code": "<authorization_code>",
      "state": "<state>",
      "redirectUri": "<redirect_uri>"
    }
  }'
```
- authorization header: Das vom Logto ausgestellte Zugangstoken (Zugangstoken (Access token)) des Benutzers.
- verificationRecordId: Die im vorherigen Schritt zurückgegebene Social Verification ID.
- connectorData: Der Autorisierungscode und alle weiteren Daten, die vom Drittanbieter während des Callbacks zurückgegeben wurden.
hinweis:
Vergiss nicht, den state-Parameter zu validieren, um CSRF-Angriffe zu verhindern.
Logto überprüft den Autorisierungscode und tauscht ihn gegen ein neues Zugangstoken (Zugangstoken (Access token)) und Auffrischungstoken (Auffrischungstoken (Refresh token)) vom Drittanbieter aus und gibt dann die Social Verification ID in der Antwort zurück.
Aktualisiere abschließend die Token-Speicherung des Benutzers, indem du den Endpunkt PATCH /my-account/identities/:target/access-token mit der Social Verification ID aufrufst:
```
curl -X PATCH https://<your-logto-domain>/my-account/identities/<target>/access-token \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "socialVerificationId": "<social_verification_id>"
  }'
```
- authorization header: Das vom Logto ausgestellte Zugangstoken (Zugangstoken (Access token)) des Benutzers.
- socialVerificationId: Die im vorherigen Schritt zurückgegebene verifizierte Social Verification Record ID.
Dadurch wird das Token-Set des Benutzers im Secret Vault von Logto mit dem neuen Zugangstoken (Zugangstoken (Access token)) und Auffrischungstoken (Auffrischungstoken (Refresh token)) aktualisiert, sodass der Benutzer auf Drittanbieter-APIs zugreifen kann, ohne sich erneut bei Logto anmelden zu müssen.

Das aktualisierte Zugangstoken (Zugangstoken (Access token)) wird zurückgegeben.

Häufige Anwendungsfälle​

Drittanbieter-Token-Speicherung aktivieren​

Social Connectors​

Enterprise SSO Connectors​

Token-Speicherung​

Überprüfung des Token-Speicherstatus​

Token-Speicherstatus​

Token-Metadaten​

Token-Abruf​

Token-Rotation​

Token-Speicherung löschen​

Tokens widerrufen​

Reauthentifizierung und Token-Erneuerung​