Föderiertes Token-Set

Ein föderiertes Token-Set ist ein Geheimnistyp, der im Secret Vault von Logto gespeichert wird und zur sicheren Verwaltung von Zugangs- und Auffrischungstokens dient, die von föderierten Drittanbieter-Identitätsanbietern ausgegeben werden. Wenn sich ein Benutzer über einen Social- oder Enterprise-SSO-Connector authentifiziert, speichert Logto die ausgegebenen 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.

Föderierte Token-Speicherung aktivieren

Social Connectors

info:

Diese Funktion ist nur für Connectors verfügbar, die die Token-Speicherung unterstützen. 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.

1. Navigiere zu Konsole > Connectors > Social Connectors.
2. Wähle den Social Connector aus, für den du die föderierte Token-Speicherung aktivieren möchtest.
3. Aktiviere auf der Seite „Einstellungen“ die Option Tokens für dauerhaften API-Zugriff speichern.

Enterprise SSO Connectors

info:

Die Token-Speicherung ist für alle OIDC-Enterprise-Connectors verfügbar.

1. Navigiere zu Konsole > Enterprise SSO.
2. Wähle den Enterprise SSO Connector aus, für den du die föderierte Token-Speicherung aktivieren möchtest.
3. 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 föderierte Token-Speicherung aktiviert ist, speichert Logto automatisch die Zugangstokens und Auffrischungstokens, die vom föderierten Identitätsanbieter ausgegeben werden, wann immer sich ein Benutzer über einen Social- oder Enterprise-SSO-Connector authentifiziert. Dies umfasst:

• Soziale Anmeldung und Registrierung
• Enterprise SSO Anmeldung und Registrierung
• Verknüpfung sozialer Konten über Account API

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 Status der föderierten Token-Speicherung eines Benutzers in der Logto-Konsole überprüfen:

1. Navigiere zu Konsole > Benutzer.
2. Klicke auf den Benutzer, den du überprüfen möchtest. Dadurch gelangst du zur Detailseite des Benutzers.
3. Scrolle zum Abschnitt Verbindungen. Dieser Bereich listet alle Social- und Enterprise-SSO-Verbindungen auf, die mit dem Benutzer verknüpft sind.
4. Jeder Eintrag zeigt ein Token-Status-Label an, das angibt, ob Tokens für diese Verbindung gespeichert sind.
5. 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 eines Benutzers und den Token-Speicherstatus über die Management API überprüfen:

• GET /api/users/{userId}/identities/{target}?includeTokenSecret=true: Ruft die Social-Identität eines Benutzers und den mit der Identität verknüpften 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 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 sich der Benutzer 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 hingegen können 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 den letzten Zeitpunkt wider, zu dem das Zugangstoken aufgefrischt wurde.
• 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 ausgegeben wird. Wenn das Zugangstoken abläuft und ein gültiges Auffrischungstoken existiert, versucht Logto automatisch, ein neues Zugangstoken mit dem gespeicherten Auffrischungstoken zu erhalten, wann immer der Benutzer Zugriff auf den verbundenen Anbieter anfordert.
• expiresAt: Die geschätzte Ablaufzeit des Zugangstokens in Sekunden. Dies wird basierend auf dem vom Token-Endpunkt des Identitätsanbieters zurückgegebenen Wert expires_in berechnet. (Dieses Feld ist nur verfügbar, wenn der Anbieter expires_in in der Token-Antwort enthält.)
• scope: Die Berechtigung (Scope) 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 zugreifst mit dem von Logto ausgegebenen Zugangstoken.

Token-Rotation

Die Endpunkte zum Token-Abruf 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 verknüpft hat oder 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 föderierte Token-Speicherung ist direkt an die Social- oder Enterprise-SSO-Verbindungen jedes Benutzers gebunden. 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ösche 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.

Erneute Authentifizierung 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-Autorisierungsflow 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 erneute Authentifizierung und Token-Erneuerung, dass der Benutzer erneut einen vollständigen Logto-Authentifizierungsflow startet, da eine direkte Re-Autorisierung mit dem Enterprise-SSO-Anbieter nach der Anmeldung derzeit nicht unterstützt wird.

1. 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 ausgegebene Zugangstoken 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. Du musst diese URI in den Anwendungseinstellungen des Anbieters registrieren.
   • scope: (Optional) Benutzerdefinierte Berechtigungen, um zusätzliche Rechte vom Drittanbieter anzufordern. Wenn nicht angegeben, werden die im Connector konfigurierten Standard-Berechtigungen verwendet.

2. 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>"
   }

3. Leite den Benutzer zur Autorisierungs-URL weiter. Der Benutzer authentifiziert sich beim Drittanbieter und erteilt Berechtigungen.

4. Der Drittanbieter leitet den Benutzer mit einem Autorisierungscode zurück zu deiner Client-Anwendung.

5. 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 ausgegebene Zugangstoken des Benutzers.
   • verificationRecordId: Die Social Verification ID aus dem vorherigen Schritt.
   • connectorData: Der Autorisierungscode und alle weiteren Daten, die vom Drittanbieter beim Callback zurückgegeben wurden.
   hinweis:

   Vergiss nicht, den state-Parameter zu validieren, um CSRF-Angriffe zu verhindern.

6. Logto überprüft den Autorisierungscode und tauscht ihn beim Drittanbieter gegen ein neues Zugangstoken und Auffrischungstoken aus und gibt dann die Social Verification ID in der Antwort zurück.

7. 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 ausgegebene 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.