Token Exchange (On-Behalf-Of)

​

Overview

​

Prerequisites

• use_idp_credentials: false (default) — a dedicated application, separate from your SSO login application, configured per MCP client via token_exchange.client_id/client_secret. This is the right default for most providers: it keeps each MCP server’s OBO grant scoped independently and limits what a leaked secret can reach.
• use_idp_credentials: true — reuses your SSO login application’s own credentials instead; client_id/client_secret are then ignored.

​

Okta: per-resource Authorization Server

1. Point the exchange at that Authorization Server explicitly. Set token_exchange.authorization_server_url to its issuer URL (e.g. https://your-domain.okta.com/oauth2/your-auth-server-id). Without this, Bifrost sends the exchange request to the same Authorization Server your SSO login uses — which has never heard of an audience registered on a different one, and Okta rejects it with invalid_target: Token Exchange requests must include a valid audience of the authorization server.
2. Register your SSO login’s Authorization Server as a Trusted Server on the resource’s Authorization Server: Security → API → (the resource’s Authorization Server) → Trusted servers → Add Server, and add the Authorization Server your SSO login uses (often default). Without this, Okta rejects the caller’s identity token as an untrusted subject with invalid_request: 'subject_token' is invalid — the audience and endpoint can be entirely correct and this still fails, since it’s a separate cross-server trust check.
3. Define a custom scope on that Authorization Server and include it in token_exchange.scopes. Standard OIDC scopes (openid, profile, email, offline_access) aren’t valid for a service-app token exchange — Okta rejects the request with invalid_scope: ... 'scope' must be provided if none is set, or rejects an OIDC scope outright. Add a scope under Security → API → (the resource’s Authorization Server) → Scopes → Add Scope (e.g. your-resource.access), grant it to the exchange application in that Authorization Server’s Access Policy, and list it in scopes.

​

Microsoft Entra ID: known setup gotchas

1. Set token_exchange.use_idp_credentials: true. This is not optional for Entra — see the warning in Prerequisites above for why a dedicated exchange application structurally cannot work. client_id/client_secret are ignored once this is set; leave them unset.
2. Token issuer mismatch — oidc: id token issued by a different provider. Whether an app’s tokens use the v1 issuer (https://sts.windows.net/<tenant>/) or the v2 issuer (https://login.microsoftonline.com/<tenant>/v2.0) is controlled by the resource app’s manifest, not by which endpoint you called. If your MCP server validates against the v2 issuer (the standard OIDC discovery shape) but gets v1 tokens, open the resource app’s registration → Manifest → set "requestedAccessTokenVersion": 2 under the api block → Save.
3. Audience mismatch — oidc: expected audience "api://..." got ["..."]. Once an app issues v2 tokens, its access tokens carry the app’s client ID (bare GUID) in aud, not the api://... Application ID URI you registered — even though you requested the scope using the URI form. Set token_exchange.audience (and the MCP server’s own audience-validation config) to the bare GUID, not api://<guid>.
4. AADSTS240002: Input id_token cannot be used as 'urn:ietf:params:oauth:grant-type:jwt-bearer' grant. The assertion Entra’s OBO endpoint accepts must be an access token, never an id_token. Bifrost’s SSO session already stores the right one for real caller traffic; this only bites when hand-crafting a token for manual testing — if you hit it, you grabbed the id_token instead of the access_token.
5. AADSTS501461: AcceptMappedClaims is only supported for a token audience matching the application GUID.... If your SSO app has custom claims mapping enabled (acceptMappedClaims: true in its manifest — typically on if you’re mapping roles/groups claims for SCIM attribute mappings), requesting an access token audienced to that app’s own api://<guid> Application ID URI is rejected outright. This only comes up when manually minting a test token against the SSO app’s own scope (e.g. <client-id>/access_as_user, not api://<client-id>/access_as_user — Entra treats an app’s own client ID as an implicit alternate resource identifier alongside its App ID URI, and that form isn’t subject to the same restriction); Bifrost’s own runtime exchange isn’t affected.
6. Adding a scope silently drops resource access. Entra’s .default scope (what audience builds by default) cannot be combined with other delegated scopes — Microsoft’s own OBO docs are explicit about this (AADSTS70011 otherwise). Bifrost handles the one documented exception automatically: scopes: ["offline_access"] combines with the default (<audience>/.default offline_access) rather than replacing it. Any other scope you configure fully replaces the default instead, per Entra’s own rule — there is no way to request .default alongside a named custom scope in the same call. If you need narrower, specific permissions rather than everything .default grants, expose named scopes on the resource app (Expose an API → Add a scope) and list only those in scopes, without .default at all.

​

Setup

• Web UI
• config.json

1. Navigate to MCP Gateway in the sidebar
2. Click New MCP Server
3. Pick HTTP or SSE as the connection type, fill in the Connection URL
4. Set Auth Type to Token Exchange (On-Behalf-Of) — only shown when an identity provider is configured
5. Fill in:
   • Audience — the resource identifier this server is registered as at your identity provider (e.g. api://jira-mcp for Okta/Auth0/Keycloak). For Microsoft Entra ID, this is the resource app’s Application (client) ID — a bare GUID, not the api://... Application ID URI shown under “Expose an API”; see Audience mismatch below for why
   • Exchange application — Dedicated application (default) or Identity provider application. Pick the latter, which reuses your SSO login application’s credentials, if your provider requires it — Microsoft Entra ID always does; see Prerequisites
   • Exchange Client ID (required) / Exchange Client Secret (optional for public clients) — only shown when Dedicated application is selected
   • Authorization Server URL (optional) — only needed if this audience is registered on a different Authorization Server than your SSO login uses; see Okta: per-resource Authorization Server
   • Scopes (optional, comma-separated) — include offline_access where your identity provider supports it, so exchanges issue refresh tokens and the retained admin discovery credential stays self-renewing. For Microsoft Entra ID specifically: offline_access is the only additional scope that combines with the audience’s default resource access — leave it as the sole entry to keep both; any other scope here replaces the default resource scope entirely rather than adding to it, and Entra rejects a .default + custom-scope combination outright — if you need narrower, specific permissions instead of the audience’s default access, list only named resource scopes here (e.g. api://jira-mcp/access_as_user), with no .default entry at all
6. Click Create — Bifrost exchanges your own signed-in identity token, verifies the upstream connection, and discovers tools

{
  "mcp": {
    "client_configs": [
      {
        "name": "jira",
        "connection_type": "http",
        "connection_string": "https://jira-mcp.internal/mcp",
        "auth_type": "token_exchange",
        "token_exchange": {
          "audience": "api://jira-mcp",
          "client_id": "env.JIRA_EXCHANGE_CLIENT_ID",
          "client_secret": "env.JIRA_EXCHANGE_CLIENT_SECRET",
          "scopes": ["jira.read", "jira.write", "offline_access"]
        },
        "tools_to_execute": ["*"]
      }
    ]
  }
}

audience is always required. client_id is required unless use_idp_credentials is true, in which case client_id/client_secret are ignored and the exchange runs as your SSO login application instead — required for Microsoft Entra ID:

"token_exchange": {
  "audience": "<entra-resource-app-client-id>",
  "use_idp_credentials": true
}

client_id and client_secret support env.VAR_NAME and vault.path references — plain values also work (encrypted at rest, redacted in API responses).At boot the client lands in pending_verification state. From the MCP Gateway UI, open the client and click Verify as me — see Verification below.

token_exchange cannot be combined with a dual_credential_conflict_behavior of error: token exchange relies on requests that may carry both an identity token and a virtual key, and error would reject exactly those requests. Creating a token_exchange client while the behavior is error (or switching the behavior to error while one exists) is rejected — see Dual-credential behavior for the setting.

​

How it works

1. The caller sends a request carrying their own identity-provider token (Authorization: Bearer <token>), or an SSO dashboard session.
2. Bifrost checks its in-memory cache for an exchanged token already minted for this (identity, mcp_client) pair.
3. On a miss, Bifrost exchanges the caller’s token at the identity provider’s token endpoint, scoped to the client’s configured audience.
4. The exchanged token is used on an ephemeral upstream connection for that call only — nothing about it is written to the database.
5. The cache holds the exchanged token until shortly before it expires, so repeat calls from the same caller don’t re-exchange every time.

​

Verification

• pending_verification — shown for a newly created or config.json-declared client with no discovered tools yet. Click Verify as me on the client sheet.
• needs_reauth — shown when the retained admin discovery credential (see below) has died and needs repair. Click Re-verify as me.

​

Admin discovery credential

​

Identity requirements

• Authorization: Bearer <IdP JWT> — validated against your SCIM identity provider, then used as the exchange subject.
• A dashboard SSO session (cookie) — the session’s stored identity-provider token is used automatically; no header needed.
• A virtual key alone — resolves identity and governance, but a tool call against a token_exchange server fails: subject_token_missing.

​

Configuration reference

{
  "auth_type": "token_exchange",
  "token_exchange": {
    "audience": "api://jira-mcp",
    "use_idp_credentials": false,
    "client_id": "***REDACTED***",
    "client_secret": "***REDACTED***",
    "authorization_server_url": "https://your-domain.okta.com/oauth2/your-auth-server-id",
    "scopes": ["jira.read", "jira.write", "offline_access"]
  }
}

​

Try it yourself

​

Next Steps

• Per-User OAuth — when the upstream server runs its own OAuth and doesn’t trust your IdP
• MCP Authentication Overview — compare all auth types
• Gateway Authentication — identity modes and dual-credential behavior