Token-Tausch (Token-Exchange)

Worum es geht

Ein Token wird immer für einen bestimmten Client ausgestellt. Meldet sich jemand im Hub an, bekommt der BFF ein Token für den Client des Hubs. Darin steht, was der Hub-Client sehen darf, und nicht unbedingt alles, was CIAS braucht: die Rollen des Backend-Clients, die Organisationen, die Attribute für den Mandanten.

Deshalb tauscht CIAS jedes eingehende Token bei Keycloak gegen eines für seinen eigenen Client ein, etwa cias-backend oder cdms-backend. Das Verfahren heißt Token-Exchange und ist ein Standard von OAuth.

Keycloak tauscht nur, wenn das eingehende Token den Client von CIAS in seiner Audience (aud) nennt. Die einzige Ausnahme: Der Client tauscht sein eigenes Token. Genau diese Regel prüft CIAS schon beim Prüfen des Tokens, sodass ein Token für einen fremden Client gar nicht erst bis zum Tausch kommt. Das getauschte Token muss als azp den Client von CIAS nennen, sonst nimmt CIAS es nicht an.

Der Vorteil: Das Frontend muss nicht wissen, welche Rollen und Claims das Backend braucht. Es schickt sein Token, CIAS besorgt sich den Rest.

Der Ablauf

sequenceDiagram
    participant C as Client
    participant S as Filterkette (CIAS)
    participant M as Cache
    participant K as Keycloak
    C->>S: Anfrage mit Token (jti = abc)
    S->>M: gibt es ein getauschtes Token für abc?
    alt Treffer
        M-->>S: getauschtes Token
    else kein Treffer
        S->>K: POST /token<br/>grant_type=token-exchange<br/>subject_token=…
        K-->>S: Token für den CIAS-Client
        S->>M: merken unter abc
    end
    S->>S: Identität aus dem getauschten Token lesen

jti ist die eindeutige ID eines Tokens, ein Claim, den Keycloak in jedes Token schreibt. Sie ist der Schlüssel des Caches.

Die Anfrage an Keycloak

Es ist derselbe Client, dessen Rollen CIAS danach aus resource_access.<client>.roles liest. So passen getauschtes Token und gelesene Rollen immer zusammen.

Die Varianten

Einstellungen

codamai:
  cias:
    token-exchange:
      ttl: 5m                 # CIAS_TOKEN_EXCHANGE_TTL
      expiry-margin: 10s      # CIAS_TOKEN_EXCHANGE_MARGIN
      max-entries: 10000      # CIAS_TOKEN_EXCHANGE_MAX_ENTRIES
      restrict-audience: false

Weiter

• Was aus dem Token gelesen wird
• Was bei jeder Anfrage mit dem Token passiert