Token Exchange

Table of Contents

This page defines the service architecture pattern Token Exchange in the pattern language. A party presents a token it holds to the issuer and receives a new token with a different subject, audience, scope or lifetime. In ORE Studio IAM mints tokens that act as a specific account and party, for orchestration inside IAM and for work that runs under a stored grant.

1. Also known as

  • Internal actor impersonation, the name ORE Studio used for the in-process form inside IAM.
  • Impersonation and delegation, the two semantics RFC 8693 defines: the new token acts as the subject alone, or as the subject with an actor named in the act claim.
  • Downscoped token, for an exchange that only narrows the scope.

2. Context

A service must call another service as an identity that no inbound request carries: an account and a party it acts for, with no caller present, or a narrower form of a token it holds. Only IAM signs tokens.

3. Problem

How does a service obtain a token for an identity, an audience or a scope that it does not already hold, without holding the signing key?

4. Forces

  • Only the issuer may sign, or every service becomes a forger.
  • The issuer must decide whether this actor may act for this subject.
  • The new token must be as narrow as the purpose: one audience, the permissions the work needs, a short lifetime.
  • An audit must show both who the token acts as and which service asked for it.
  • An exchange per request makes the issuer a bottleneck.

5. Solution

The service sends the issuer a request with the actor token, its own, and the subject it wants to act as: a subject token, or a reference such as a grant id. It also names the audience and the scope it needs. The issuer checks that the actor may exchange for that subject, narrows the permissions to the scope, sets a short lifetime, records the issue, and signs. The new token names the subject in sub and the actor in act. The service uses it until shortly before it expires.

pattern_token_exchange.png

Figure 1: Token Exchange: the service presents its own token and the subject, and IAM returns a narrow, short-lived token that names both.

Source: [[./pattern_token_exchange.puml][pattern_token_exchange.puml]]. Regenerate with plantuml -tpng doc/knowledge/service_architecture_patterns/pattern_token_exchange.puml.

RFC 8693 defines two semantics, and they produce different tokens. With impersonation the new token names only the subject, so the target cannot tell a service asked. With delegation it also names the actor in act.

pattern_token_exchange_semantics.png

Figure 2: Token Exchange: an impersonation token names only the subject; a delegation token also names the service that asked, in the act claim.

Source: [[./pattern_token_exchange_semantics.puml][pattern_token_exchange_semantics.puml]]. Regenerate with plantuml -tpng doc/knowledge/service_architecture_patterns/pattern_token_exchange_semantics.puml.

6. Failure handling

Concern What the pattern does
Errors A refused exchange answers forbidden with a reason. The reason is final for that subject: the caller fails its work and does not retry.
Timeouts The exchange is a request with a short timeout. A caller that cannot reach the issuer retries with back-off inside its own budget, then fails.
Retries A target that answers token_expired causes one new exchange and one retry of the request. Any other refusal fails the request. A refusal is never retried with the same token.
Idempotency An exchange is safe to repeat; each one returns a new token. Concurrent misses for one subject share one exchange.
Observability The issuer logs every issue: the subject, the actor, the audience, the scope and the expiry. A refused exchange logs the reason.

7. Pitfalls

  • A token shorter than the work. A token minted for one call expires during a long poll. The first version of internal impersonation retried until the wait timed out, because it treated token_expired as a busy server. The fix is one new exchange on token_expired, and a clear failure otherwise. See Internal actor impersonation and Commission Acme Corporation.
  • An exchange per request. Without a cache, the issuer serves every call of every service. Cache the token until shortly before it expires.
  • A token wider than the purpose. An exchanged token with the subject's full permissions is a session for that subject. Narrow it to the scope the work needs.
  • Exchange where Token Relay fits. When the identity to act as is the request's own caller, relay the caller's token. Exchange only when no such token exists.

8. Security

The exchange is the most powerful operation in the identity group: it creates an identity. Three rules bound it. Only actors that hold an exchange permission may call it, and only for subjects they are allowed to act for. The token is narrow and short. Every issue is recorded. A leaked exchanged token acts for its subject within its scope until it expires, and names the service that obtained it.

9. Resulting context

Benefits
A service can act as a tenant and a party with no caller and no signing key. Every token is narrow and attributable.
Liabilities
The issuer is on the path of new work, so its availability matters, and the caller needs a cache.

10. In ORE Studio

  • Inside IAM. internal_impersonation_service::mint_token mints a token as a given account and party, and internal_request_client re-mints once on token_expired. Tenant provisioning drives several parties this way. See Internal actor impersonation.
  • Over the bus. IAM serves the exchange as iam.v1.ops.exchange_run_grant for work that runs under a grant. The subject is a grant id, the actor is the step service's own token, and the new token lasts five minutes. See Run grants and run tokens for IAM's checks and claims.

11. Related patterns

12. Sources

  • RFC 8693, OAuth 2.0 Token Exchange, section 1.1 for impersonation and delegation, and section 4.1 for the act claim.
  • Neil Madden, API Security in Action, Manning, 2020, chapter 11, "Securing service-to-service APIs".

13. See also

Emacs 29.3 (Org mode 9.6.15)