Token Exchange

Token Exchange (RFC 8693) ist ein OAuth 2.0-Erweiterungsgrant, der es einem privilegierten Dienst erlaubt, ein vorhandenes Token gegen ein neues Token einzutauschen, das entweder:

• Die Identität eines anderen Benutzers annimmt (Impersonation): Das sub im neuen Token ist der Zielbenutzer, nicht der anfragende Dienst.
• Im Namen eines anderen Dienstes handelt (Delegation): Das sub im neuen Token ist dasselbe, aber der act-Claim zeichnet den delegierenden Dienst auf.

Impersonation-Token-Struktur

{
  "sub": "target-user-id",
  "email": "[email protected]",
  "roles": ["member"],
  "act": {
    "sub": "admin-user-id",
    "email": "[email protected]"
  },
  "iat": 1700000000,
  "exp": 1700003600
}

Das act-Claim zeigt immer die Person oder den Dienst, der tatsächlich handelt — wesentlich für Audit-Logs.

Delegations-Token-Struktur

{
  "sub": "original-user-id",
  "aud": "backend-service",
  "act": {
    "sub": "frontend-service-client-id"
  },
  "scope": "read:invoices",
  "iat": 1700000000,
  "exp": 1700003600
}

Einrichten

1. Öffne die Auris Console → Applications → deine Anwendung.
2. Navigiere zu Advanced → Token Exchange und aktiviere es.
3. Konfiguriere, welche Exchange-Typen erlaubt sind: Impersonation, Delegation oder beide.
4. Weise der aufrufenden Client-Anwendung die erforderlichen Berechtigungen zu:
   • Für Impersonation: impersonate:users
   • Für Delegation: delegate:tokens

Verwendung

import { AurisManagementClient } from '@auris/js'
 
const mgmt = new AurisManagementClient({
  domain: process.env.AURIS_DOMAIN,
  clientId: process.env.AURIS_CLIENT_ID,
  clientSecret: process.env.AURIS_CLIENT_SECRET,
})
 
// Impersonation — handeln als target-user
const impersonatedToken = await mgmt.auth.exchangeToken({
  subjectToken: existingAccessToken,
  subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
  requestedTokenType: 'urn:ietf:params:oauth:token-type:access_token',
  requestedSubject: 'user-id-to-impersonate',
  audience: 'https://api.yourdomain.com',
  scope: 'read:invoices view:profile',
})
 
console.log(impersonatedToken.access_token) // Token mit sub = Zielbenutzer
 
// Delegation — im Auftrag des ursprünglichen Benutzers gegenüber einem Backend handeln
const delegatedToken = await mgmt.auth.exchangeToken({
  subjectToken: userAccessToken,
  subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
  requestedTokenType: 'urn:ietf:params:oauth:token-type:access_token',
  audience: 'backend-service',
  scope: 'read:invoices',  // Scope kann nur eingeschränkt werden
})

# Schritt 1: M2M-Token für den Dienst abrufen
curl -X POST https://auth.yourdomain.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-service-client-id",
    "client_secret": "your-service-client-secret",
    "scope": "impersonate:users"
  }'
 
# Schritt 2: Token Exchange durchführen
curl -X POST https://auth.yourdomain.com/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "client_id": "your-service-client-id",
    "client_secret": "your-service-client-secret",
    "subject_token": "EXISTING_ACCESS_TOKEN",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_subject": "target-user-id",
    "audience": "https://api.yourdomain.com",
    "scope": "read:invoices"
  }'

Anfrage-Parameter

Verschachtelte Delegationsketten

Der act-Claim kann verschachtelt werden, um mehrstufige Delegation aufzuzeichnen:

{
  "sub": "user-123",
  "act": {
    "sub": "api-gateway-client-id",
    "act": {
      "sub": "frontend-service-client-id"
    }
  }
}

Dies zeigt: frontend-service delegierte an api-gateway, der nun im Namen von user-123 handelt. Jede Ebene ist im Token vollständig nachvollziehbar.

Ausgetauschte Tokens validieren

Im Backend solltest du ausgetauschte Tokens identifizieren und entsprechend handeln:

import { verifyToken } from '@auris/node'
 
const payload = await verifyToken(accessToken, {
  domain: process.env.AURIS_DOMAIN!,
  audience: process.env.AURIS_AUDIENCE!,
})
 
if (payload.act) {
  // Dieses Token ist das Ergebnis eines Token Exchange
  const effectiveSubject = payload.sub        // Wer handelt
  const originalActor   = payload.act.sub    // Wer hat initiiert
 
  // Für Audit-Logs immer beide protokollieren
  logger.info('Token Exchange erkannt', {
    effectiveSubject,
    originalActor,
    action: req.method + ' ' + req.path,
  })
 
  // Hochriskante destruktive Operationen für imitierte Tokens blockieren
  if (isDestructiveOperation(req) && effectiveSubject !== originalActor) {
    return res.status(403).json({ error: 'Destruktive Operationen durch Impersonation nicht erlaubt' })
  }
}

Sicherheitshinweise

• Scope kann nur eingeschränkt werden: Ein ausgetauschtes Token darf nie einen breiteren Scope haben als das Ursprungs-Token.
• Vertraulicher Client erforderlich: Öffentliche Clients können keinen Token Exchange durchführen.
• 1-Stunden-Lebensdauer: Ausgetauschte Tokens laufen standardmäßig nach 1 Stunde ab, unabhängig von der Ursprungs-Token-Lebensdauer.
• Vollständiges Audit-Logging: Alle Token-Exchanges werden im Auris Audit-Log protokolliert — wer hat für wen getauscht, wann und für welchen Scope.
• Impersonation-Schutz: Verwende act-Claim-Prüfungen in deiner API, um imitierte Tokens von regulären Tokens zu unterscheiden.

API-Referenz

Berechtigungen

Verwandte Anleitungen

• M2M Client Credentials — Service-Tokens, die für Token Exchange verwendet werden
• Rollen & Berechtigungen (RBAC) — Berechtigungen für Token Exchange zuweisen
• Audit Logs — Token-Exchange-Aktivitäten überwachen