Add backend authentication concepts documentation #281
Conversation
Adds conceptual documentation for MCP-server-to-backend authentication, complementing the existing client-to-MCP-server authentication guide. The new document explains: - Token exchange patterns for backend service authentication - Two implementation approaches: same IdP token exchange and federated IdP identity mapping with services like Google STS - Security and multi-tenancy benefits of using short-lived tokens - How ToolHive eliminates the need for embedded credentials in MCP servers Includes Mermaid diagrams showing authentication flows and example token transformations for both standard and federated scenarios. This addresses the gap mentioned in auth-framework.mdx where backend authentication was noted as requiring separate documentation. Related: #240
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation for backend authentication in ToolHive, explaining how MCP servers authenticate to external services through token exchange and federated identity patterns.
- Introduces a new "Backend authentication" documentation page covering token exchange mechanisms
- Updates cross-references between authentication documentation pages
- Adds the new page to the documentation sidebar
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| sidebars.ts | Adds the new backend-auth page to the concepts section of the documentation sidebar |
| docs/toolhive/concepts/backend-auth.mdx | New comprehensive documentation explaining backend authentication patterns, token exchange flows, and federation mechanisms for MCP servers |
| docs/toolhive/concepts/auth-framework.mdx | Updates references to backend authentication documentation and adds cross-reference links in the Related information section |
| MCP[MCP Server] | ||
| Upstream[Upstream Service] | ||
| User -->|login & receive token_A| IDP1 | ||
| IDP1 -->|submit token_A| IDP2 | ||
| IDP2 -->|issue token_B| IDP1 | ||
| IDP1 -->|pass token_B| MCP |
There was a problem hiding this comment.
The mermaid diagram flow is inaccurate. The arrows "IDP1 -->|submit token_A| IDP2" and "IDP2 -->|issue token_B| IDP1" suggest IDP1 communicates with IDP2, but according to the "How it works" section and the overall architecture described, it's ToolHive that submits token_A to the federated identity service (IDP2) and receives token_B. IDP1 doesn't directly interact with IDP2 in this flow.
| MCP[MCP Server] | |
| Upstream[Upstream Service] | |
| User -->|login & receive token_A| IDP1 | |
| IDP1 -->|submit token_A| IDP2 | |
| IDP2 -->|issue token_B| IDP1 | |
| IDP1 -->|pass token_B| MCP | |
| ToolHive[ToolHive] | |
| MCP[MCP Server] | |
| Upstream[Upstream Service] | |
| User -->|login & receive token_A| IDP1 | |
| IDP1 -->|pass token_A| ToolHive | |
| ToolHive -->|submit token_A| IDP2 | |
| IDP2 -->|issue token_B| ToolHive | |
| ToolHive -->|pass token_B| MCP |
| MCP[MCP Server] | ||
| Upstream[Upstream Service] | ||
| User -->|login & receive token| IDP | ||
| MCP -->|subject_token → exchange| IDP | ||
| IDP -->|external_token issued| MCP |
There was a problem hiding this comment.
The mermaid diagram flow doesn't accurately represent the token exchange process. The arrow "MCP -->|subject_token → exchange| IDP" suggests the MCP Server initiates the exchange, but according to the "How it works" section and the sequence diagram later, it's actually ToolHive (acting as middleware) that performs the token exchange with the IdP, not the MCP Server itself. The MCP Server only receives and uses the already-exchanged token.
| MCP[MCP Server] | |
| Upstream[Upstream Service] | |
| User -->|login & receive token| IDP | |
| MCP -->|subject_token → exchange| IDP | |
| IDP -->|external_token issued| MCP | |
| ToolHive[ToolHive Middleware] | |
| MCP[MCP Server] | |
| Upstream[Upstream Service] | |
| User -->|login & receive token| IDP | |
| ToolHive -->|subject_token → exchange| IDP | |
| IDP -->|external_token issued| ToolHive | |
| ToolHive -->|external_token| MCP |
danbarr
left a comment
danbarr
left a comment
There was a problem hiding this comment.
Fantastic! Just one very minor suggestion from me, and not sure if Copilot's are valid, but this looks great.
| The MCP specification focuses on authorization to the MCP server but doesn't | ||
| specify how an MCP server should authenticate to the services it exposes. This | ||
| is intentionally left to implementers, which makes sense from a specification | ||
| perspective but leaves MCP server creators without clear guidance. |
|
|
||
| ToolHive supports multiple patterns for obtaining external access tokens, | ||
| depending on the relationship between your identity provider (IdP) and the | ||
| external service. All patterns assume OAuth-based authentication—for services |
There was a problem hiding this comment.
All patterns assume OAuth-based authentication. For services using other
authentication methods (such as database
connections with static credentials),
consider integrations with secret
management systems like HashiCorp Vault.
|
|
||
| ### Token transformation | ||
|
|
||
| When a client authenticates to ToolHive, they receive a token scoped for the MCP |
There was a problem hiding this comment.
it receives (client is singular)
1. Fixed Federated IdP diagram to show ToolHive middleware performing token exchange (not IDP1 communicating directly with IDP2) 2. Fixed token exchange diagram to show ToolHive middleware initiating exchange (not MCP Server) 3. Changed "back end" to "backend" for consistency 4. Added link to HashiCorp Vault integration tutorial 5. Fixed grammar: "they receive" → "it receives" (client is singular) 6. Changed "MCP server creators" → "MCP server developers" 7. Reformatted OAuth paragraph for clarity (em dash → period, "like" → "such as")
jhrozek
force-pushed
the
be_auth_docs_concepts
branch
from
673edbd to
46c02b3
Compare
The new document explains:
Includes Mermaid diagrams showing authentication flows and example token transformations for both standard and federated scenarios.
This addresses the gap mentioned in auth-framework.mdx where backend authentication was noted as requiring separate documentation.
Related: #240
Description
Adds conceptual documentation for MCP-server-to-backend authentication, complementing the existing client-to-MCP-server authentication guide.
Related issues/PRs
#240
Screenshots
N/A
Merge checklist
Content
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (i.e., if the URL slug changed)Reviews
I've done my best to review for style but I'm not sure I feel confident ticking that box.