Drittanbieter-Token-Speicherung & API-Zugriff

Das Drittanbieter-Token-Set (auch als föderiertes Token-Set bekannt) ist ein Geheimnistyp, der im Secret Vault von Logto gespeichert wird, um Zugriffs- und Auffrischungstokens, 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 angemeldet hat, kann deine Produktivitäts-App automatisch dessen 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. All dies 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 der Benutzer 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 bei der Erneuerung von Tokens für den Drittanbieter-API-Zugriff gespeichert werden. Derzeit 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) für den Zugriff auf bestimmte Drittanbieter-APIs.
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. Zugriffs- und Auffrischungstokens können während des Enterprise Single Sign-On gespeichert werden. Derzeit 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) für den Zugriff auf bestimmte Drittanbieter-APIs.
Aktiviere im Tab „SSO-Erfahrung“ die Option Tokens für dauerhaften API-Zugriff speichern.

Vergiss nicht, deine Änderungen zu speichern.

Token-Speicherung

Sobald die Drittanbieter-Token-Speicherung aktiviert ist, speichert Logto automatisch die Zugriffs- und Auffrischungstokens, die vom föderierten Identitätsanbieter ausgestellt werden, 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. Dadurch gelangst du 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 Zugriffs-Token-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 prüfen:

GET /api/users/{userId}/identities/{target}?includeTokenSecret=true: Ruft die Social-Identität eines Benutzers und den zugehörigen 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 zugehörigen Token-Speicherstatus für eine bestimmte SSO-Connector-ID ab.

Token-Speicherstatus

Aktiv: Das Zugangstoken ist gespeichert und aktiv.
Abgelaufen: Das Zugangstoken ist gespeichert, aber abgelaufen. Wenn ein Auffrischungstoken verfügbar ist, kann damit ein neues Zugangstoken abgerufen werden.
Inaktiv: Für diese Verbindung ist kein Zugangstoken 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

Zur Wahrung 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 verfügbar ist, entspricht dieser Wert createdAt.
- Wenn ein Auffrischungstoken vorhanden ist, spiegelt dieser Wert die letzte Aktualisierung des Zugangstokens wider.
hasRefreshToken: Gibt an, ob ein Auffrischungstoken verfügbar ist. Wenn der Connector Offline-Zugriff unterstützt und die Autorisierungsanfrage entsprechend konfiguriert ist, speichert Logto das Auffrischungstoken, wenn es vom Identitätsanbieter zusammen mit dem Zugangstoken ausgestellt wird. Wenn das Zugangstoken abläuft und ein gültiges Auffrischungstoken existiert, versucht Logto automatisch, ein neues Zugangstoken mit dem gespeicherten Auffrischungstoken zu erhalten, sobald der Benutzer Zugriff auf den verbundenen Anbieter anfordert.
expiresAt: Die geschätzte Ablaufzeit des Zugangstokens 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 des Zugangstokens, die die vom Identitätsanbieter gewährten Berechtigungen angibt. Dies ist nützlich, um zu verstehen, welche Aktionen mit dem gespeicherten Zugangstoken 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, 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 aus deiner Client-Anwendung abrufen, indem sie die User Account API von Logto integrieren.

GET /my-account/identities/:target/access-token: Ruft das Zugangstoken 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 für eine Enterprise-SSO-Identität ab, indem die Connector-ID angegeben wird.

info:

Erfahre, wie du die Account API aktivierst und auf die Account API mit dem von Logto ausgestellten Zugangstoken zugreifst.

Token-Rotation

Die Token-Abruf-Endpunkte liefern:

200 OK: Wenn das Zugangstoken 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 nicht gespeichert ist.
401 Nicht autorisiert: Wenn das Zugangstoken abgelaufen ist.

Wenn das Zugangstoken abgelaufen ist und ein Auffrischungstoken verfügbar ist, versucht Logto automatisch, das Zugangstoken zu erneuern und gibt das neue Zugangstoken in der Antwort zurück. Die Token-Speicherung im Secret Vault wird ebenfalls mit dem neuen Zugangstoken und dessen 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 (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 zu erhalten, bevor er wieder auf Drittanbieter-APIs zugreifen kann.

Reauthentifizierung und Token-Erneuerung

In Szenarien, in denen ein gespeichertes Zugangstoken abgelaufen ist oder eine Anwendung zusätzliche API-Berechtigungen anfordern muss, können Endbenutzer sich beim Drittanbieter erneut authentifizieren, um ein frisches Zugangstoken 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 startet, da eine direkte Reautorisierung mit dem Enterprise-SSO-Anbieter nach der Anmeldung derzeit nicht unterstützt wird.

Der Benutzer initiiert 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 des Benutzers.
- connectorId: Die Social Connector ID in Logto.
- redirectUri: Die URI, zu der der Benutzer nach der Authentifizierung in deine Anwendung zurückgeleitet wird. Diese URI muss in den Anwendungseinstellungen des Anbieters registriert werden.
- scope: (Optional) Benutzerdefinierte Berechtigungen, um zusätzliche Rechte 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 sowie die 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 des Benutzers.
- verificationRecordId: Die im vorherigen Schritt zurückgegebene Social Verification ID.
- connectorData: Der Autorisierungscode und weitere Daten, die vom Drittanbieter beim Callback 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 und Auffrischungstoken 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 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 und Auffrischungstoken aktualisiert, sodass der Benutzer auf Drittanbieter-APIs zugreifen kann, ohne sich erneut bei Logto anmelden zu müssen.

Das aktualisierte Zugangstoken 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​