docs: add use_idp_credentials to token_exchange config, make client_id optional when set, and document Entra ID requirement with updated prerequisites and gotchas

[Pratham-Mishra04]

Summary

Adds use_idp_credentials to the token_exchange auth type, allowing the token exchange to run as the SSO login application itself rather than a separately registered dedicated exchange application. This is required for Microsoft Entra ID, whose on-behalf-of grant enforces that the assertion's audience matches the exchanging application — a structural constraint that makes a dedicated exchange application impossible to use with Entra.

Changes

• Added use_idp_credentials: boolean (default false) to MCPTokenExchangeConfig across the config schema, OpenAPI spec, and management YAML schema. When true, client_id and client_secret are ignored and the exchange uses the SSO login application's credentials instead.
• client_id is no longer unconditionally required — the schema now enforces it conditionally: required unless use_idp_credentials: true is set.
• authorization_server_url was added to the transport config schema where it was previously missing.
• Updated the token exchange documentation to explain the two exchange application modes, why Entra structurally requires use_idp_credentials: true (with a citation to Microsoft's own OBO reference), and how RFC 8693 providers differ from Entra's pre-standard OBO grant.
• Reorganized the Microsoft Entra ID known-gotchas list to lead with setting use_idp_credentials: true as step 1, since without it no other Entra troubleshooting step is relevant.
• Updated the UI setup instructions to reflect the new Exchange application selector (Dedicated vs. Identity provider application) and the conditional display of client ID/secret fields.
• Added a use_idp_credentials: false field to the reference API response example for completeness.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Configure an MCP client with auth_type: token_exchange against a Microsoft Entra ID tenant:

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

1. Verify the client reaches pending_verification state without a schema validation error (previously would have failed requiring client_id).
2. Click Verify as me — the exchange should succeed and the client move to verified.
3. Confirm that omitting both use_idp_credentials: true and client_id still fails schema validation.
4. Confirm that a non-Entra provider (Okta, Auth0) still works with use_idp_credentials: false and an explicit client_id.

Breaking changes

• Yes
• No

client_id is no longer required at the schema level when use_idp_credentials: true is set. Existing configs that supply client_id are unaffected. No previously valid configuration becomes invalid.

Security considerations

use_idp_credentials: true causes the exchange to use the SSO login application's own credentials, which are shared across all MCP clients configured this way. This is intentional and required for Entra, but means a misconfigured audience could result in tokens being minted for unintended resources using the SSO application's grant. The per-client audience field remains the scope boundary. client_id and client_secret continue to be redacted in API responses and support env.VAR_NAME/vault.path references.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• docs: add use_idp_credentials to token_exchange config, make client_id optional when set, and document Entra ID requirement with updated prerequisites and gotchas #6069 👈 (View in Graphite)
• feat: add use_idp_credentials to token-exchange config, allowing SSO login app credentials to be reused for providers like Microsoft Entra ID that require it #6068
• docs: move token-exchange screenshot above steps and add pending_verification state copy to verify dialog #6063
• docs: add quarterly (1Q) budget reset with reset_config/quarter_start_month, Entra ID OBO gotchas, and clarify token-exchange app registration guidance #6062
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Token exchange can now use SSO identity-provider credentials instead of a separate exchange application.
  • Added an optional authorization server URL override.
  • Configuration validation supports conditional client credential requirements, with separate credentials ignored when SSO credentials are enabled.

• Documentation

  • Updated setup guides, configuration references, API schemas, examples, and troubleshooting guidance, including Microsoft Entra ID requirements.

Walkthrough

The token exchange configuration now supports SSO identity-provider credentials. Schemas, OpenAPI definitions, validation rules, and Microsoft Entra ID documentation describe conditional use of client_id and client_secret.

Changes

Token exchange SSO support

Layer / File(s)	Summary
Configuration schema contracts transports/config.schema.json, docs/openapi/schemas/management/mcp.yaml	Token exchange schemas add use_idp_credentials and conditional client_id validation. The transport schema also adds authorization_server_url.
OpenAPI schema synchronization docs/openapi/openapi.json	Five token exchange definitions require only audience, add use_idp_credentials, and document conditional client credential handling.
Token exchange documentation docs/mcp/auth/token-exchange.mdx, docs/deployment-guides/config-json/schema-reference.mdx	Guides document SSO setup, Microsoft Entra ID requirements, troubleshooting, examples, defaults, and field behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• maximhq/bifrost#6060: Both changes update MCP token_exchange schemas and validation.
• maximhq/bifrost#6062: Both changes update token exchange documentation and Microsoft Entra ID guidance.
• maximhq/bifrost#6068: Both changes cover the use_idp_credentials token-exchange feature.

Suggested reviewers: akshaydeo, danpiths, bearts

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and specifically summarizes the primary configuration and documentation changes.
Description check	✅ Passed	The description covers the purpose, changes, testing steps, impact, security considerations, and checklist; omitted sections are not critical for this documentation-focused PR.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 08-11-docs_mcp_token_exhcange_doc_updates

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/mcp/auth/token-exchange.mdx`:
- Around line 99-100: Update the token-exchange documentation wording so
Exchange Client ID is required when Dedicated application is selected, while
only Exchange Client Secret remains optional for public clients. Align the
guidance with transports/config.schema.json: client_id is required unless
use_idp_credentials is true.

In `@docs/openapi/openapi.json`:
- Around line 43557-43576: Update all eight token_exchange schema sites in
docs/openapi/openapi.json at lines 43557-43576, 43413, 43673, 43933,
43817-43836, 44077-44096, 44328-44347, and 93041-93060 to include the
conditional allOf requirement from transports/config.schema.json, requiring
client_id unless use_idp_credentials is true. Preserve audience,
authorization_server_url, and the existing properties and descriptions.

In `@docs/openapi/schemas/management/mcp.yaml`:
- Around line 19-49: Update the MCPTokenExchangeConfig schema to match the
token-exchange validation contract: reject configurations missing client_id
unless use_idp_credentials is true, and reject unknown properties by preserving
additionalProperties: false. Use the corresponding transports/config.schema.json
rules as the source of truth while retaining the documented field definitions.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: db0d4c8f-87d8-448b-a9ec-c07f1b5f1fb2

📥 Commits

Reviewing files that changed from the base of the PR and between 60cb165 and 4b35e05.

📒 Files selected for processing (5)

• docs/deployment-guides/config-json/schema-reference.mdx
• docs/mcp/auth/token-exchange.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/mcp.yaml
• transports/config.schema.json

[akshaydeo]

Merge activity

• Aug 11, 4:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 11, 4:51 PM UTC: Graphite rebased this pull request as part of a merge.
• Aug 11, 4:52 PM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.