---
schema_version: "1"
id: cfb917be29d18bf6338ebf402a9453ea12150006ec9463ee0151de07a240391b
title: OAuth 2.0 OBO Credential Injection Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-outbound-oauth-obo.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-outbound-oauth-obo
source_site: docs.mulesoft.com
content_type: documentation
content_hash: aa8bc9608ea7117952e597ad55f1690d58dccc3ef70af1bbf505483d0abef1b0
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: oauth2, token exchange, on-behalf-of, obo, rfc 8693, api gateway, flex gateway, gateway, policy
---

# OAuth 2.0 OBO Credential Injection Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>OAuth 2.0 OBO Credential Injection</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>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</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.11.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/outbound-oauth-obo-release-notes">OAuth 2.0 OBO Credential Injection</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy. Error codes are returned from the upstream service.</p></td></tr></tbody></table>

## 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 Omni Replicas. To learn more, see
[Token Caching](#token-caching-oauth-obo).

## Configuring Policy Parameters

### Omni Gateway Local Mode

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

### Managed Omni Gateway and Omni Gateway Connected Mode

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

<table><colgroup><col> <col></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Token Exchange Flow</p></div></div></td><td><div><div><p>Token exchange flow: <strong>OAuth 2.0 Token Exchange</strong> (RFC 8693) or <strong>Microsoft Entra ID On-Behalf-Of</strong>.</p></div></div></td></tr><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p>OAuth 2.0 client ID for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Client Secret</p></div></div></td><td><div><div><p>OAuth 2.0 client secret for token exchange.</p></div></div></td></tr><tr><td><div><div><p>Token Endpoint</p></div></div></td><td><div><div><p>OAuth 2.0 token endpoint URL.</p></div></div></td></tr><tr><td><div><div><p>Target Type</p></div></div></td><td><div><div><p>Parameter type for specifying the target service. Required for OAuth 2.0 Token Exchange flow. Supported values:</p></div><div><ul><li><p>Audience: Logical identifier of the target service (default)</p></li><li><p>Resource: Physical URI of the target resource (RFC 8707)</p></li></ul></div></div></td></tr><tr><td><div><div><p>Target Value</p></div></div></td><td><div><div><p>Target audience URI or resource URI for the exchanged token. Required for OAuth 2.0 Token Exchange flow.</p></div></div></td></tr><tr><td><div><div><p>Requested Token Type</p></div></div></td><td><div><div><p>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.</p></div></div></td></tr><tr><td><div><div><p>Subject Token Type</p></div></div></td><td><div><div><p>The token type URI for the incoming subject token from the request <code>Authorization</code> header. By default <code>urn:ietf:params:oauth:token-type:access_token</code>. For JWT tokens, use <code>urn:ietf:params:oauth:token-type:jwt</code>. OAuth 2.0 Token Exchange flow only.</p></div></div></td></tr><tr><td><div><div><p>Scope</p></div></div></td><td><div><div><p>OAuth 2.0 scope to request. Required for Microsoft Entra OBO (for example, <code>api://downstream-client-id/.default</code>) and OAuth2 Token Exchange with CIBA (for example, <code>openid</code>). Optional for OAuth 2.0 Token Exchange (RFC 8693).</p></div></div></td></tr><tr><td><div><div><p>Timeout</p></div></div></td><td><div><div><p>Timeout for token exchange requests in milliseconds. Default: 10000.</p></div></div></td></tr><tr><td><div><div><p>Enable CIBA</p></div></div></td><td><div><div><p>Enables OAuth 2.0 Token Exchange with CIBA flow. Available only for OAuth 2.0 Token Exchange.</p></div></div></td></tr><tr><td><div><div><p>CIBA Backchannel Endpoint</p></div></div></td><td><div><div><p>The backchannel authentication endpoint (<code>bc-authorize</code>) used to initiate the CIBA flow. Required when <strong>Enable CIBA</strong> is selected.</p></div></div></td></tr><tr><td><div><div><p>Login Hint Claim</p></div></div></td><td><div><div><p>JWT claim from the incoming subject token to send as <code>login_hint</code> in the CIBA request. If no hint is specified, <code>email</code> is used.</p></div></div></td></tr><tr><td><div><div><p>Binding Message</p></div></div></td><td><div><div><p>Optional human-readable message sent as <code>binding_message</code> in the CIBA request and displayed on the authentication device.</p></div></div></td></tr><tr><td><div><div><p>Distributed</p></div></div></td><td><div><div><p>When enabled, the token cache and CIBA request state are shared across Omni Gateway replicas. Enable this option when running more than one replica to avoid duplicate token exchanges or duplicate CIBA initiations.</p></div></div></td></tr></tbody></table>

## 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." }