Skip to content

Commit 544f4a0

Browse files
committed
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)
1 parent b935b3d commit 544f4a0

File tree

1 file changed

+83
-2
lines changed

1 file changed

+83
-2
lines changed

docs/toolhive/guides-k8s/auth-k8s.mdx

Lines changed: 83 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@ You'll need:
3333

3434
## Choose your authentication approach
3535

36-
There are two main ways to authenticate with MCP servers running in Kubernetes:
36+
There are three main ways to authenticate with MCP servers running in
37+
Kubernetes:
3738

3839
### Approach 1: External identity provider authentication
3940

@@ -44,7 +45,18 @@ providers like Google, GitHub, Microsoft Entra ID, Okta, or Auth0.
4445

4546
<OidcPrerequisites />
4647

47-
### Approach 2: Kubernetes service-to-service authentication
48+
### Approach 2: Shared OIDC configuration with ConfigMap
49+
50+
Use this when you want to share the same OIDC configuration across multiple
51+
MCPServers. This is ideal for managing multiple servers with the same external
52+
identity provider.
53+
54+
**Prerequisites for shared OIDC:**
55+
56+
- External identity provider configured (same as Approach 1)
57+
- Understanding of Kubernetes ConfigMaps
58+
59+
### Approach 3: Kubernetes service-to-service authentication
4860

4961
Use this when you have client applications running in the same Kubernetes
5062
cluster that need to call MCP servers. This approach uses Kubernetes service
@@ -122,6 +134,75 @@ For Kubernetes service accounts, tokens are automatically mounted at
122134

123135
:::
124136

137+
## Set up shared OIDC configuration with ConfigMap
138+
139+
### Step 1: Create OIDC ConfigMap
140+
141+
Create a ConfigMap containing the OIDC configuration:
142+
143+
```yaml title="shared-oidc-config.yaml"
144+
apiVersion: v1
145+
kind: ConfigMap
146+
metadata:
147+
name: shared-oidc-config
148+
namespace: toolhive-system
149+
data:
150+
oidc.json: |
151+
{
152+
"issuer": "https://auth.example.com",
153+
"audience": "https://mcp.example.com",
154+
"clientId": "shared-client-id",
155+
"jwksUrl": "https://auth.example.com/.well-known/jwks.json"
156+
}
157+
```
158+
159+
```bash
160+
kubectl apply -f shared-oidc-config.yaml
161+
```
162+
163+
### Step 2: Reference ConfigMap in MCPServer
164+
165+
Create MCPServer resources that reference the shared configuration:
166+
167+
```yaml title="mcp-server-with-configmap-oidc.yaml"
168+
apiVersion: toolhive.stacklok.dev/v1alpha1
169+
kind: MCPServer
170+
metadata:
171+
name: weather-server-shared-oidc
172+
namespace: toolhive-system
173+
spec:
174+
image: ghcr.io/stackloklabs/weather-mcp/server
175+
transport: sse
176+
port: 8080
177+
permissionProfile:
178+
type: builtin
179+
name: network
180+
# Reference shared OIDC configuration
181+
oidcConfig:
182+
type: configMap
183+
configMap:
184+
name: shared-oidc-config
185+
key: oidc.json
186+
resources:
187+
limits:
188+
cpu: '100m'
189+
memory: '128Mi'
190+
requests:
191+
cpu: '50m'
192+
memory: '64Mi'
193+
```
194+
195+
```bash
196+
kubectl apply -f mcp-server-with-configmap-oidc.yaml
197+
```
198+
199+
### Benefits of ConfigMap approach
200+
201+
- **Centralized management**: Update OIDC settings in one place
202+
- **Consistency**: Ensure all MCPServers use identical authentication config
203+
- **GitOps friendly**: Manage configuration separately from MCPServer resources
204+
- **Multi-server deployments**: Deploy multiple servers with same auth easily
205+
125206
## Set up Kubernetes service-to-service authentication
126207

127208
This approach is ideal when you have client applications running in the same

0 commit comments

Comments
 (0)