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​

Nach dem Einrichten der Management API kannst du die API-Endpunkte verwenden, um persönliche Zugriffstokens zu erstellen, aufzulisten und zu löschen.

PATs verwenden, um Zugangstokens zu gewähren​

Nach dem Erstellen eines PAT kannst du diesen verwenden, um deiner Anwendung Zugangstokens über den Token-Exchange-Endpunkt zu gewähren.

Tokenfluss-Äquivalenz:

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

  • Organisationskontext: Über PATs erhaltene Tokens unterstützen die gleichen Organisationsberechtigungen und Berechtigungen (Scopes) wie Refresh-Token-Flows
  • Autorisierungsfluss: Du kannst PAT-ausgetauschte Zugangstokens für Organisationsberechtigungen und organisationsbezogene API-Ressourcen verwenden
  • Tokenvalidierung: Die gleiche Validierungslogik gilt – nur der anfängliche Grant-Typ unterscheidet sich

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

Anfrage​

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​

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&scope=profile
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGci...zg",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile"
}

Das Beispiel-Payload des Zugangstokens:

{
  "jti": "iFtbZBeh2M1cTTBuKbHk4",
  "sub": "123",
  "iss": "https://tenant.logto.app/oidc",
  "exp": 1672531200,
  "iat": 1672527600,
  "scope": "profile",
  "client_id": "client-id"
}

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

Persönliche Zugriffstokens, Maschine-zu-Maschine-Authentifizierung und API-Schlüssel: Definition und reale Anwendungsfälle