Contact Us 1-800-596-4880
  1. Homepage
  2. Flex Gateway (1.12)
  3. Securing Flex Gateway Instances with Policies
  4. Outbound Policies Directory

  5. OAuth 2.0 OBO Credential Injection

OAuth 2.0 OBO Credential Injection Policy

Policy Name

OAuth 2.0 OBO Credential Injection

Summary

Exchanges incoming bearer tokens using OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of, or OAuth 2.0 Token Exchange with CIBA

Category

Security

First Flex Gateway version available

v1.11.0

Returned Status Codes

No return codes exist for this policy. Error codes are returned from the upstream service.

Summary

The OAuth 2.0 On-Behalf-Of (OBO) Credential Injection policy exchanges an incoming bearer token for a new token to target specific upstream services. The policy supports OAuth 2.0 Token Exchange (RFC 8693), Microsoft Entra ID On-Behalf-Of protocols, and OAuth 2.0 Token Exchange with Client Initiated Backchannel Authentication (CIBA). This policy is applied to outbound traffic (gateway to the backend service) to automatically exchange the OAuth 2.0 token needed for backend services.

The policy extracts the Bearer token from the incoming request’s Authorization header and sends a token exchange request to the token endpoint. The policy then replaces the Authorization header with the new token returned from the token exchange service and forwards the modified request to the backend service.

To avoid triggering multiple requests for identical tokens, successful token exchanges are cached. By default, the cache only shares tokens between requests to the same replica. Enable distributed caching to share tokens between Flex Replicas. To learn more, see Token Caching.

Configuring Policy Parameters

Flex Gateway Local Mode

The OAuth 2.0 OBO Credential Injection policy isn’t supported in Local Mode.

Managed Flex Gateway and Flex Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

Parameter Description

Token Exchange Flow

Token exchange flow: OAuth 2.0 Token Exchange (RFC 8693) or Microsoft Entra ID On-Behalf-Of.

Client ID

OAuth 2.0 client ID for token exchange.

Client Secret

OAuth 2.0 client secret for token exchange.

Token Endpoint

OAuth 2.0 token endpoint URL.

Target Type

Parameter type for specifying the target service. Required for OAuth 2.0 Token Exchange flow. Supported values:

  • Audience: Logical identifier of the target service (default)

  • Resource: Physical URI of the target resource (RFC 8707)

Target Value

Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange flow.

Requested Token Type

The desired token type URI for the issued token. When omitted, the parameter is not sent and the authorization server selects the issued token type. OAuth 2.0 Token Exchange flow only.

Subject Token Type

The token type URI for the incoming subject token from the request Authorization header. By default urn:ietf:params:oauth:token-type:access_token. For JWT tokens, use urn:ietf:params:oauth:token-type:jwt. OAuth 2.0 Token Exchange flow only.

Scope

OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, api://downstream-client-id/.default) and OAuth2 Token Exchange with CIBA (for example, openid). Optional for OAuth 2.0 Token Exchange (RFC 8693).

Timeout

Timeout for token exchange requests in milliseconds. Default: 10000.

Enable CIBA

Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.

CIBA Backchannel Endpoint

The backchannel authentication endpoint (bc-authorize) used to initiate the CIBA flow. Required when Enable CIBA is selected.

Login Hint Claim

JWT claim from the incoming subject token to send as login_hint in the CIBA request. If no hint is specified, email is used.

Binding Message

Optional human-readable message sent as binding_message in the CIBA request and displayed on the authentication device.

Distributed

When enabled, the token cache and CIBA request state are shared across Flex Gateway replicas. Enable this option when running more than one replica to avoid duplicate token exchanges or duplicate CIBA initiations.

Token Caching

The policy stores each exchanged downstream access token and reuses it when later requests present the same token. Cached entries are tied to a stable key and expire in line with the token’s lifetime:

  • TTL: Cache entry lifetime is derived from the exchanged token.

  • If the policy cannot determine expiry, it skips caching for that response. If the policy cannot build a cache key, it performs the exchange without using the cache.

  • When Enable CIBA is enabled, CIBA initiation and polling state, including the approved access token, is cached through the same mechanism.

CIBA Behavior

When Enable CIBA is selected, the policy initiates a CIBA backchannel authentication request on the first matching outbound call and returns an authorization pending response until user authentication is approved by the authorization server. After approval, the policy injects the exchanged access token into the Authorization header and forwards requests to the backend service.

While waiting for user authentication, the policy returns a 401 Unauthorized response with the following JSON body:

HTTP/1.1 401 Unauthorized
Retry-After: 5
Content-Type: application/json

{
  "error": "authorization_pending",
  "error_description": "CIBA authorization flow initiated. Downstream user authorization is in progress. Retry after the indicated interval."
}