Skip to main content

On-Behalf-Of (OBO) Delegations

Console View​

OBO Delegations Console

Identity Broker supports the RFC 8693 OAuth 2.0 Token Exchange protocol, which enables the On-Behalf-Of (OBO) delegation flow. This allows a middle-tier service (like an API gateway or backend microservice) to exchange a user's access token for a token that can be used to call a downstream service, while still preserving the user's original identity.

Why Use OBO?​

In a microservices architecture, you often have a chain of services. When a user calls Service A, which in turn needs to call Service B, Service A should not simply pass the user's original token to Service B. Instead, it should exchange it for a new token that is specifically intended for Service B (different audience and potentially different scopes).

Delegation Relationships​

OBO in Identity Broker is governed by Delegation Relationships. You must explicitly define which services are allowed to perform token exchanges for which target audiences.

Key Fields​

  • Source Client: The application that will initiate the token exchange (e.g., api-gateway). This must be a Confidential Client (with a client secret).
  • Target Audience: The client identifier of the downstream service for which the new token will be issued (e.g., user-service).
  • Allowed Scopes: The maximum set of scopes that can be granted in the issued OBO token.
  • Require Scope Downscoping: If enabled, the system ensures that the requested scopes are a subset of the original user token's scopes.
  • Enabled: Quickly toggle the delegation relationship on or off.

Token Exchange Flow​

  1. User Authentication: The user authenticates with Identity Broker and receives an access token for the api-gateway.
  2. Service Call: The user calls the api-gateway including their access token in the Authorization header.
  3. Token Exchange: The api-gateway calls the Identity Broker's token endpoint (/oauth2/token) using the urn:ietf:params:oauth:grant-type:jwt-bearer grant type.
    • It sends the user's access token as the assertion.
    • It specifies the audience as user-service.
  4. Validation: Identity Broker validates:
    • The user's token is valid and not expired.
    • A delegation relationship exists between api-gateway and user-service.
    • The user's token has not been replayed (using the Token Replay Cache).
    • The requested scopes are allowed.
  5. Issue Token: Identity Broker issues a new access token with the user-service as the audience and the user's original sub (subject).

Token Replay Prevention​

To prevent a compromised assertion token from being used multiple times, Identity Broker implements a Token Replay Cache.

  • Every assertion token's unique identifier (jti) is tracked.
  • If a token with the same jti is used again, the exchange request is rejected.
  • This ensures that each user token can only be exchanged for an OBO token once.

Actor Claim (act)​

Identity Broker supports the actor (act) claim as defined in RFC 8693. The issued OBO token includes an act claim that identifies the client that performed the exchange. This provides a clear audit trail of who is acting on behalf of the user.

Example token payload:

{
  "sub": "usr_a1b2c3d4",
  "aud": "user-service",
  "iss": "https://idp.identix.com",
  "act": {
    "sub": "api-gateway"
  }
}

Monitoring and Auditing​

The OBO Exchange History section in the Admin Console provides a complete log of all token exchange events, including:

  • Timestamp of the exchange.
  • Source and target clients.
  • User subject identifier.
  • Success or failure status (with error details).
  • Scopes requested and granted.

This level of visibility is critical for troubleshooting and security auditing.