Skip to content

Commit 7e95d41

Browse files
ChrisJBurnsdanbarrjhrozek
authored
Add auth docs (#233)
* adds start for auth docs Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> * Fix issues breaking the build Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> * Add to sidebar, remove duplicate doc Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> * Rename files to mdx, fix up admonition syntax Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> * Move JSON comments in Cedar policy example above the example Remove inline // comments from JSON code block as they are invalid JSON syntax and will cause parsing errors. Move explanations to bullet points above the example for better clarity. * Fix Kubernetes CRD field structures for OIDC and authz config Update all MCPServer YAML examples to use correct CRD field structure: 1. External IdP authentication: - Change spec.auth.oidc → spec.oidcConfig - Add required type: inline field - Nest configuration under inline: key 2. Kubernetes service account authentication: - Change spec.auth.oidc → spec.oidcConfig - Use type: kubernetes instead of inline - Replace clientId with serviceAccount and namespace fields 3. Authorization configuration: - Change spec.auth.authorization → spec.authzConfig - Add required type: configMap field - Update field names: configMapName → name, configMapKey → key These changes align with the actual ToolHive CRD definitions in toolhive/cmd/thv-operator/api/v1alpha1/mcpserver_types.go * Add thv logs additional flags to troubleshooting docs Document --follow and --proxy flags for the thv logs command to help users debug authentication issues more effectively: - --follow: Follow logs in real-time (like tail -f) - --proxy: View proxy logs instead of container logs * Add ConfigMap OIDC type example for shared authentication Add a new approach (Approach 2) showing how to use ConfigMaps to share OIDC configuration across multiple MCPServer resources. This provides: - Centralized management of OIDC settings - Consistency across multiple servers - GitOps-friendly configuration management - Easier multi-server deployments Updated section numbering: - Approach 1: External identity provider (inline config) - Approach 2: Shared OIDC configuration (ConfigMap) - Approach 3: Kubernetes service-to-service (service accounts) * Add scope clarification to auth framework documentation Add an info admonition at the beginning of the auth framework concept document to explicitly clarify that this documentation covers client-to-MCP-server authentication, not MCP-server-to-backend authentication. This distinction helps readers understand: - What is covered: How clients authenticate to the MCP server - What is not covered: How MCP servers authenticate to external APIs (e.g., GitHub MCP server authenticating to GitHub API) The note indicates that MCP-server-to-backend authentication will be covered in separate future documentation. * Update client authentication support section Revise the "Client support for MCP server authentication" section to reflect the current state of the MCP ecosystem more accurately: - Remove outdated claim that "most clients do not support authentication" - Acknowledge that authentication support varies across clients - Simplify guidance to recommend looking for clients that support MCP authentication standards (OAuth 2.1 and transport-level auth) - Remove redundant use cases section (already covered elsewhere in docs) - Remove "Expected evolution" and "Planning for the future" subsections The revised section is more concise and reflects that while authentication support is not universal, many clients now support it to varying degrees. * Update authentication framework terminology for OAuth 2.1/OIDC and token diversity This updates the authentication framework concepts documentation to: - Add link to official MCP spec and clarify OAuth resource server role - Update from OIDC-only to OAuth 2.1/OIDC throughout - Document support for both JWT and opaque tokens - Add new "Token validation methods" section explaining local JWT validation and remote token introspection (RFC 7662, Google, GitHub) - Update diagrams to use generic "Access Token" and "Identity Provider" instead of "JWT" and "OIDC Provider" - Update authorization flow from "JWT middleware" to "authentication middleware" - Clarify automatic token type detection (JWT first, then introspection fallback) * Minor formatting tweaks Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --------- Signed-off-by: ChrisJBurns <29541485+ChrisJBurns@users.noreply.github.com> Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Co-authored-by: Jakub Hrozek <jakub@stacklok.com>
1 parent a813425 commit 7e95d41

File tree

8 files changed

+1423
-0
lines changed

8 files changed

+1423
-0
lines changed

‎docs/toolhive/_partials/_auth-troubleshooting.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
<details>
2+
<summary>Authentication issues</summary>
3+
4+
If clients can't authenticate:
5+
6+
1. Check that the JWT token is valid and not expired
7+
2. Verify that the audience and issuer match your configuration
8+
3. Ensure the JWKS URL is accessible
9+
4. Check the server logs for specific authentication errors:
10+
11+
```bash
12+
# View logs
13+
thv logs <server-name>
14+
15+
# Follow logs in real-time (like tail -f)
16+
thv logs <server-name> --follow
17+
18+
# View proxy logs instead of container logs
19+
thv logs <server-name> --proxy
20+
```
21+
22+
</details>
23+
24+
<details>
25+
<summary>Authorization issues</summary>
26+
27+
If authenticated clients are denied access:
28+
29+
1. Make sure your Cedar policies explicitly permit the specific action
30+
(remember, default deny)
31+
2. Check that the principal, action, and resource match what's in your policies
32+
(including case and formatting)
33+
3. Examine any conditions in your policies to ensure they're satisfied (for
34+
example, required JWT claims or tool arguments)
35+
4. Remember that Cedar uses a default deny policy—if no policy explicitly
36+
permits an action, it will be denied
37+
38+
**Troubleshooting tip:** If access is denied, check that your policies
39+
explicitly permit the action. Cedar uses a default deny model—if no policy
40+
matches, the request is denied.
41+
42+
</details>

‎docs/toolhive/_partials/_basic-cedar-config.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
Create a JSON or YAML file with Cedar policies. This example demonstrates
2+
several policy patterns:
3+
4+
- Allow everyone to use the weather tool
5+
- Restrict the admin_tool to a specific user (alice123)
6+
- Role-based access: only users with the "premium" role can call any tool
7+
- Attribute-based: allow the calculator tool only for add/subtract operations
8+
9+
Here's an example in JSON format:
10+
11+
```json
12+
{
13+
"version": "1.0",
14+
"type": "cedarv1",
15+
"cedar": {
16+
"policies": [
17+
"permit(principal, action == Action::\"call_tool\", resource == Tool::\"weather\");",
18+
"permit(principal == Client::\"alice123\", action == Action::\"call_tool\", resource == Tool::\"admin_tool\");",
19+
"permit(principal, action == Action::\"call_tool\", resource) when { principal.claim_roles.contains(\"premium\") };",
20+
"permit(principal, action == Action::\"call_tool\", resource == Tool::\"calculator\") when { resource.arg_operation == \"add\" || resource.arg_operation == \"subtract\" };"
21+
],
22+
"entities_json": "[]"
23+
}
24+
}
25+
```
26+
27+
You can also define custom resource attributes in `entities_json` for per-tool
28+
ownership or sensitivity labels.
29+
30+
:::tip
31+
32+
For more policy examples and advanced usage, see
33+
[Cedar policies](../concepts/cedar-policies.mdx).
34+
35+
:::

‎docs/toolhive/_partials/_oidc-prerequisites.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Before you begin, make sure you have:
2+
3+
- ToolHive installed and working
4+
- Basic familiarity with OAuth, OIDC, and JWT concepts
5+
- An identity provider that supports OpenID Connect (OIDC), such as Google,
6+
GitHub, Microsoft Entra ID (Azure AD), Okta, Auth0, or Kubernetes (for service
7+
accounts)
8+
9+
From your identity provider, you'll need:
10+
11+
- Client ID
12+
- Audience value
13+
- Issuer URL
14+
- JWKS URL (for key verification)
15+
16+
ToolHive uses OIDC to connect to your existing identity provider, so you can
17+
authenticate with your own credentials (for example, Google login) or with
18+
service account tokens (for example, in Kubernetes). ToolHive never sees your
19+
password, only signed tokens from your identity provider.
20+
21+
For background on authentication, authorization, and Cedar policy examples, see
22+
[Authentication and authorization framework](../concepts/auth-framework.mdx).

‎docs/toolhive/concepts/auth-framework.mdx‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
---
2+
title: Authentication and authorization
3+
description:
4+
Understanding ToolHive's authentication and authorization framework concepts.
5+
---
6+
7+
This document explains the concepts behind ToolHive's authentication and
8+
authorization framework, which secures MCP servers by verifying client identity
9+
and controlling access to resources. You'll learn how these systems work
10+
together, why they're designed this way, and the benefits of this approach.
11+
12+
:::info[Scope of this documentation]
13+
14+
This documentation covers **client-to-MCP-server authentication**—how clients
15+
authenticate to the MCP server itself. This is about securing access to the MCP
16+
server's tools and resources.
17+
18+
This is different from **MCP-server-to-backend authentication**, which involves
19+
how the MCP server authenticates to external services or APIs it calls (for
20+
example, a GitHub MCP server authenticating to the GitHub API). That topic will
21+
be covered in separate documentation.
22+
23+
:::
24+
25+
## Understanding authentication vs. authorization
26+
27+
When you secure MCP servers, you need to understand the strong separation
28+
between two critical security concepts:
29+
30+
- **Authentication (authN):** Verifying the identity of clients connecting to
31+
your MCP server ("Who are you?")
32+
- **Authorization (authZ):** Determining what actions authenticated clients are
33+
allowed to perform ("What can you do?")
34+
35+
You should always perform authentication first, using a trusted identity
36+
provider, and then apply authorization rules to determine what the authenticated
37+
identity can do. ToolHive helps you follow this best practice by acting as a
38+
gateway in front of your MCP servers. This approach lets you use proven identity
39+
systems for authentication, while keeping your authorization policies clear,
40+
flexible, and auditable. You don't need to add custom authentication or
41+
authorization logic to every server—ToolHive handles it for you, consistently
42+
and securely.
43+
44+
## ToolHive vs. MCP specification
45+
46+
The
47+
[official Model Context Protocol (MCP) specification](https://modelcontextprotocol.io/docs/tutorials/security/authorization)
48+
recommends OAuth 2.1-based authorization for HTTP transports, which requires
49+
each MCP server to act as an OAuth resource server that validates access tokens
50+
and enforces scope-based access control. ToolHive takes a different approach: it
51+
centralizes authentication and authorization in its proxy layer, using
52+
OAuth/OIDC for authentication and Cedar for fine-grained authorization. This
53+
means you don't need to implement token validation or scope management in every
54+
server—just configure ToolHive with your IdP and write clear Cedar policies.
55+
This approach is more flexible, secure, and easier to manage for you and your
56+
team.
57+
58+
## Authentication framework
59+
60+
ToolHive uses OAuth-based authentication with support for both OAuth 2.1 and
61+
OpenID Connect (OIDC), enabling both JWT tokens and opaque token validation.
62+
This lets you connect ToolHive to any OAuth 2.1 or OIDC-compliant identity
63+
provider (IdP), such as Google, GitHub, Microsoft Entra ID (Azure AD), Okta,
64+
Auth0, or even Kubernetes service accounts. ToolHive never handles your raw
65+
passwords or credentials; instead, it relies on access tokens issued by your
66+
trusted provider—either self-contained JWT tokens or opaque tokens validated
67+
through token introspection.
68+
69+
### Why use OAuth-based authentication?
70+
71+
OAuth-based authentication provides several key advantages for securing MCP
72+
servers:
73+
74+
- **Standard and interoperable:** You can connect ToolHive to any OAuth 2.1 or
75+
OIDC-compliant IdP without custom code, supporting both human users and
76+
automated services.
77+
- **Proven and secure:** Authentication is delegated to battle-tested identity
78+
systems, which handle login UI, multi-factor authentication, and password
79+
storage.
80+
- **Decoupled identity management:** You can use your existing SSO/IdP
81+
infrastructure, making onboarding and management seamless.
82+
- **Flexible for users and services:** This authentication framework supports
83+
both interactive user login (for example, Google sign-in) and
84+
service-to-service authentication (for example, Kubernetes service account
85+
tokens).
86+
87+
### Real-world authentication scenarios
88+
89+
Understanding how OAuth-based authentication works in practice helps you design
90+
better security for your MCP servers:
91+
92+
**User login via Google:** For example, you can run an MCP server that requires
93+
authentication using your Google credentials. ToolHive delegates login to
94+
Google, receives an access token (either a JWT or an opaque token), and
95+
validates it to authenticate you. This means users get a familiar login
96+
experience while you benefit from Google's security infrastructure.
97+
98+
**Service-to-service auth with Kubernetes:** If you run a microservice in a
99+
Kubernetes cluster, it can present its service account token (typically an OIDC
100+
JWT) to ToolHive. ToolHive validates the token using the cluster's OIDC issuer
101+
and JWKS endpoint, enabling secure, automated authentication for your internal
102+
services.
103+
104+
### Token-based authentication
105+
106+
ToolHive supports two types of access tokens for authentication:
107+
108+
**JWT tokens (JSON Web Tokens):** Self-contained tokens that include identity
109+
information within the token itself. JWTs are validated locally using
110+
cryptographic signatures and consist of three parts:
111+
112+
1. **Header:** Metadata about the token
113+
2. **Payload:** Claims about the entity (typically you or your service)
114+
3. **Signature:** Ensures the token hasn't been altered
115+
116+
**Opaque tokens:** Reference tokens that don't contain identity information
117+
directly. ToolHive validates these tokens by querying the identity provider's
118+
token introspection endpoint to retrieve the associated claims.
119+
120+
ToolHive automatically detects the token type and uses the appropriate
121+
validation method—attempting JWT validation first and falling back to token
122+
introspection if needed.
123+
124+
### Authentication flow
125+
126+
The authentication process follows these steps:
127+
128+
1. **Token acquisition:** You obtain an access token from your identity
129+
provider.
130+
2. **Token presentation:** You include the token in your requests to ToolHive
131+
(typically in the Authorization header).
132+
3. **Token validation:** ToolHive validates the token using either:
133+
- **Local validation:** For JWT tokens, verifying the signature, expiration,
134+
and claims using the provider's public keys (JWKS)
135+
- **Remote validation:** For opaque tokens, querying the provider's token
136+
introspection endpoint to verify the token and retrieve claims
137+
4. **Identity extraction:** ToolHive extracts your identity information from the
138+
validated token claims.
139+
140+
```mermaid
141+
flowchart TD
142+
Client -->|Access Token| ToolHive
143+
ToolHive -->|Validate Token| Identity_Provider[Identity Provider]
144+
ToolHive -->|Evaluate Cedar Policy| Cedar_Authorizer[Cedar Authorizer]
145+
Cedar_Authorizer -->|Permit| MCP_Server
146+
Cedar_Authorizer -->|Deny| Denied[403 Forbidden]
147+
```
148+
149+
### Identity providers
150+
151+
ToolHive can integrate with any provider that supports OAuth 2.1 or OIDC,
152+
including:
153+
154+
- Google
155+
- GitHub
156+
- Microsoft Entra ID (Azure AD)
157+
- Okta
158+
- Auth0
159+
- Kubernetes (service account tokens)
160+
161+
This flexibility lets you use your existing identity infrastructure for both
162+
users and services, reducing operational overhead and improving security.
163+
164+
### Token validation methods
165+
166+
ToolHive supports multiple token validation methods to work with different
167+
identity providers:
168+
169+
- **JWT validation:** For providers that issue JWT tokens, ToolHive validates
170+
tokens locally using the provider's JWKS endpoint. This verifies the token's
171+
signature, expiration, and claims without calling the identity provider for
172+
each request.
173+
- **Token introspection:** For providers that issue opaque tokens, ToolHive
174+
validates tokens by querying the provider's introspection endpoint. This
175+
supports RFC 7662 (OAuth 2.0 Token Introspection), Google's tokeninfo API, and
176+
GitHub's token validation API.
177+
178+
ToolHive automatically detects the token type—it first attempts JWT validation,
179+
and if that fails, it falls back to token introspection. This means you don't
180+
need to configure which validation method to use; ToolHive handles it
181+
automatically based on the token format.
182+
183+
## Authorization framework
184+
185+
After authentication, ToolHive enforces authorization using Amazon's Cedar
186+
policy language. ToolHive acts as a gateway in front of MCP servers, handling
187+
all authorization checks before requests reach the server logic. This means MCP
188+
servers do not need to implement their own OAuth or custom authorization
189+
logic—ToolHive centralizes and standardizes access control.
190+
191+
### Why Cedar for authorization?
192+
193+
Cedar provides several advantages for MCP server authorization:
194+
195+
- **Expressive and flexible:** Cedar supports both role-based (RBAC) and
196+
attribute-based (ABAC) access control patterns, letting you create policies
197+
that match your security requirements.
198+
- **Formally verified:** Cedar's design has been formally verified for safety
199+
and security properties, which reduces the risk of policy bugs.
200+
- **Human-readable:** Cedar policies use clear, declarative syntax that's easy
201+
to read, write, and audit.
202+
- **Policy enforcement point:** ToolHive blocks unauthorized requests before
203+
they reach the MCP server, which reduces risk and simplifies server code.
204+
- **Secure by default:** Authorization is explicit—if a request is not
205+
explicitly permitted, it is denied. Deny rules take precedence over permit
206+
rules (deny overrides).
207+
208+
### Authorization components
209+
210+
ToolHive's authorization framework consists of:
211+
212+
1. **Cedar authorizer:** Evaluates Cedar policies to determine if a request is
213+
authorized
214+
2. **Authorization middleware:** Extracts information from MCP requests and uses
215+
the Cedar Authorizer
216+
3. **Configuration:** A JSON or YAML file that specifies the Cedar policies and
217+
entities
218+
219+
### Authorization flow
220+
221+
When a request arrives at an MCP server with authorization enabled:
222+
223+
1. The authentication middleware authenticates the client and adds token claims
224+
to the request context
225+
2. The authorization middleware extracts information from the request
226+
(principal, action, resource, and any arguments)
227+
3. The Cedar authorizer evaluates policies to determine if the request is
228+
authorized
229+
4. If authorized, the request proceeds; otherwise, a 403 Forbidden response is
230+
returned
231+
232+
```mermaid
233+
flowchart TD
234+
Client -->|Access Token| ToolHive
235+
ToolHive -->|Validate Token| Auth_Middleware
236+
Auth_Middleware -->|Extract Claims| Authz_Middleware
237+
Authz_Middleware -->|Evaluate Cedar Policies| Cedar_Authorizer
238+
Cedar_Authorizer -->|Permit| MCP_Server
239+
Cedar_Authorizer -->|Deny| Denied[403 Forbidden]
240+
```
241+
242+
## Security and operational benefits
243+
244+
ToolHive's authentication and authorization approach provides several key
245+
benefits:
246+
247+
- **Separation of concerns:** Authentication and authorization are handled
248+
independently, following security best practices.
249+
- **Integration with existing systems:** Use your existing identity
250+
infrastructure (SSO, IdPs, Kubernetes, etc.).
251+
- **Centralized, flexible policy model:** Define precise, auditable access rules
252+
in a single place—no need to modify MCP server code.
253+
- **Secure by default:** Requests are denied unless explicitly permitted by
254+
policy, with deny precedence for maximum safety.
255+
- **Auditable and versionable:** Policies are clear, declarative, and can be
256+
tracked in version control for compliance and review.
257+
- **Developer and operator friendly:** ToolHive acts as a smart proxy, so you
258+
don't need to implement complex OAuth or custom auth logic in every server.
259+
260+
## Client authentication support
261+
262+
While ToolHive provides a robust authentication and authorization framework for
263+
MCP servers, authentication support varies across the MCP client ecosystem.
264+
265+
### MCP client capabilities
266+
267+
The MCP ecosystem includes numerous clients with varying levels of
268+
authentication support. Authentication support is not universal. Some clients
269+
focus primarily on local, unauthenticated MCP servers for development workflows,
270+
while others provide enterprise-grade authentication for production deployments.
271+
272+
When selecting an MCP client for authenticated workflows, look for clients that
273+
support the MCP authentication standards, including OAuth 2.1 and
274+
transport-level authentication mechanisms.
275+
276+
ToolHive's OIDC-based authentication approach aligns with industry standards and
277+
works with clients that support modern authentication protocols. As the MCP
278+
ecosystem continues to mature, we expect authentication support to become more
279+
standardized across clients.
280+
281+
## Related information
282+
283+
- For detailed policy writing guidance, see
284+
[Cedar policies](./cedar-policies.mdx)

0 commit comments

Comments
 (0)