Skip to content

Simplify authentication docs to tested configurations #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 2, 2025
Merged

Simplify authentication docs to tested configurations #343

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 13 additions & 32 deletions docs/toolhive/guides-vmcp/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,12 @@ spec:
type: anonymous
```

:::warning

Never use `anonymous` incoming authentication in production environments.

:::

### OIDC authentication

Validate tokens from an external identity provider:
Expand Down Expand Up @@ -112,51 +118,26 @@ validates service account tokens. The defaults work for most clusters:

## Outgoing authentication

Configure how Virtual MCP authenticates to backend MCP servers. Outgoing
authentication is configured through `MCPExternalAuthConfig` resources.
Configure how Virtual MCP authenticates to backend MCP servers.

### Discovery mode (recommended)
### Discovery mode

When using discovery mode, Virtual MCP checks each backend MCPServer's
`externalAuthConfigRef` to determine how to authenticate. If a backend has no
auth config, Virtual MCP uses the specified default.
auth config, Virtual MCP connects without authentication.

```yaml
spec:
outgoingAuth:
source: discovered
default:
type: discovered
```

### External auth config reference

Reference an `MCPExternalAuthConfig` resource for specific backends:

```yaml
spec:
outgoingAuth:
source: inline
backends:
github:
type: external_auth_config_ref
externalAuthConfigRef:
name: github-auth
```

The `MCPExternalAuthConfig` resource defines the actual authentication strategy:

- **Token exchange**: Exchange the client's token for a backend-specific token
using RFC 8693
- **Header injection**: Inject a static header value (such as an API key)

{/* TODO: Add MCPExternalAuthConfig examples */}

## Example: Complete authentication setup

{/* TODO: Add complete authentication example */}
This is the recommended approach for most deployments. Backends that don't
require authentication work automatically, while backends with
`externalAuthConfigRef` configured use their specified authentication method.

## Related information

- [Authentication framework concepts](../concepts/auth-framework.mdx)
- [VirtualMCPServer configuration](./configuration.mdx)
- [Token exchange in Kubernetes](../guides-k8s/token-exchange-k8s.mdx)
Loading