Zum Hauptinhalt springen

Persönlicher Zugriffstoken

Persönliche Zugriffstokens (PATs) bieten eine sichere Möglichkeit für Benutzer, einen Zugangstoken (Access token) zu gewähren, ohne ihre Zugangsdaten und eine interaktive Anmeldung zu verwenden. Dies ist nützlich für CI / CD, Skripte oder Anwendungen, die programmatisch auf Ressourcen zugreifen müssen.

Verwaltung persönlicher Zugriffstokens​

Über die Konsole​

Du kannst persönliche Zugriffstokens auf der Seite Benutzerdetails der Konsole > Benutzerverwaltung verwalten. In der Karte "Authentifizierung (Authentication)" siehst du die Liste der persönlichen Zugriffstokens und kannst neue erstellen.

Über die Management API​

Nachdem du die Management API eingerichtet hast, kannst du die API-Endpunkte verwenden, um persönliche Zugriffstokens zu erstellen, aufzulisten und zu löschen.

PATs verwenden, um Zugangstokens zu gewähren​

Nachdem du ein PAT erstellt hast, kannst du es verwenden, um Zugangstokens für deine Anwendung über den Token-Exchange-Endpunkt zu gewähren.

Token-Flow-Äquivalenz:

Mit PATs erhaltene Zugangstokens funktionieren identisch wie Tokens, die über den Standard-refresh_token-Flow erhalten wurden. Das bedeutet:

  • Organisationskontext: Mit PAT erhaltene Tokens unterstützen die gleichen Organisationsberechtigungen und Berechtigungen (Scopes) wie Refresh-Token-Flows
  • Autorisierungs-Flow: Du kannst PAT-getauschte Zugangstokens für Organisationsberechtigungen und organisationsbezogene API-Ressourcen verwenden
  • Token-Validierung: Die gleiche Validierungslogik gilt – nur der initiale Grant-Typ unterscheidet sich

Wenn du mit Organisationen arbeitest, sind die Zugriffsmuster und Berechtigungen gleich, unabhängig davon, ob du PAT oder Refresh-Tokens verwendest.

Anfrage​

Voraussetzungen:

Bevor du den Token-Austausch-Grant verwenden kannst, musst du ihn für deine Anwendung aktivieren:

  1. Gehe zu Konsole > Anwendungen und wähle deine Anwendung aus.
  2. Suche in den Anwendungseinstellungen den Abschnitt „Token-Austausch“.
  3. Aktiviere den Schalter „Token-Austausch erlauben“.

Der Token-Austausch ist aus Sicherheitsgründen standardmäßig deaktiviert. Wenn du ihn nicht aktivierst, erhältst du einen Fehler „Token-Austausch ist für diese Anwendung nicht erlaubt“.

Die Anwendung stellt eine Token-Exchange-Anfrage an den Token-Endpunkt des Tenants mit einem speziellen Grant-Typ über die HTTP-POST-Methode. Die folgenden Parameter werden im HTTP-Request-Entity-Body im Format application/x-www-form-urlencoded übergeben.

  1. client_id: ERFORDERLICH. Die Client-ID der Anwendung.
  2. grant_type: ERFORDERLICH. Der Wert dieses Parameters muss urn:ietf:params:oauth:grant-type:token-exchange sein und zeigt an, dass ein Token-Austausch durchgeführt wird.
  3. resource: OPTIONAL. Der Ressourcenindikator, wie bei anderen Token-Anfragen.
  4. scope: OPTIONAL. Die angeforderten Berechtigungen (Scopes), wie bei anderen Token-Anfragen.
  5. subject_token: ERFORDERLICH. Das PAT des Benutzers.
  6. subject_token_type: ERFORDERLICH. Der Typ des im Parameter subject_token bereitgestellten Sicherheitstokens. Der Wert dieses Parameters muss urn:logto:token-type:personal_access_token sein.

Antwort​

Wenn die Token-Exchange-Anfrage erfolgreich ist, gibt der Token-Endpunkt des Tenants einen Zugangstoken zurück, der die Identität des Benutzers repräsentiert. Die Antwort enthält die folgenden Parameter im HTTP-Response-Entity-Body im Format application/json.

  1. access_token: ERFORDERLICH. Der Zugangstoken des Benutzers, wie bei anderen Token-Anfragen wie authorization_code oder refresh_token.
  2. issued_token_type: ERFORDERLICH. Der Typ des ausgegebenen Tokens. Der Wert dieses Parameters muss urn:ietf:params:oauth:token-type:access_token sein.
  3. token_type: ERFORDERLICH. Der Typ des Tokens. Der Wert dieses Parameters muss Bearer sein.
  4. expires_in: ERFORDERLICH. Die Lebensdauer des Zugangstokens in Sekunden.
  5. scope: OPTIONAL. Die Berechtigungen (Scopes) des Zugangstokens.

Beispiel für einen Token-Austausch​

Für traditionelle Webanwendungen oder Maschine-zu-Maschine-Anwendungen mit App-Secret gib die Zugangsdaten im Authorization-Header mit HTTP-Basic-Authentifizierung an:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(app-id:app-secret)>

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

Für Single-Page-Anwendungen (SPA) oder native Anwendungen ohne App-Secret gib client_id im Request-Body an:

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded

client_id=your-app-id
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&resource=http://my-api.com
&scope=read
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn:logto:token-type:personal_access_token

Eine erfolgreiche Antwort:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

Wenn du dann den Zugangstoken mit dem JWT-Decoder dekodierst, erhältst du folgendes Beispiel für einen Zugangstoken-Payload:

{
  "jti": "VovNyqJ5_tuYac89eTbpF",
  "sub": "rkxl1ops7gs1",
  "iat": 1756908403,
  "exp": 1756912003,
  "scope": "read",
  "client_id": "your-app-id",
  "iss": "https://tenant-id.logto.app/oidc",
  "aud": "http://my-api.com"
}

Was ist ein persönlicher Zugriffstoken? Wann sollte ich persönliche Zugriffstokens verwenden?

Persönliche Zugriffstokens, Maschine-zu-Maschine-Authentifizierung und API-Keys – Definition und ihre Anwendungsfälle in der Praxis