@@ -15,7 +15,7 @@ sequenceDiagram
15
15
participant Client
16
16
participant Gateway as MCP Gateway
17
17
participant MCP as MCP Server
18
-
18
+
19
19
Client->>Client: Generate JWT Token
20
20
Client->>Gateway: Request + Bearer Token
21
21
Gateway->>Gateway: Validate JWT
@@ -37,7 +37,7 @@ sequenceDiagram
37
37
participant IDP as Identity Provider
38
38
participant Gateway as MCP Gateway
39
39
participant MCP as MCP Server
40
-
40
+
41
41
User->>Proxy: Request
42
42
Proxy->>IDP: Validate Session
43
43
IDP-->>Proxy: User Identity
@@ -92,9 +92,9 @@ graph LR
92
92
OAuth -->|X-Auth-Request-User| Gateway[MCP Gateway]
93
93
Gateway --> MCP1[MCP Server 1]
94
94
Gateway --> MCP2[MCP Server 2]
95
-
95
+
96
96
OAuth -.->|OAuth Flow| IDP[Google/GitHub/etc]
97
-
97
+
98
98
style OAuth fill:#f9f,stroke:#333,stroke-width:2px
99
99
style Gateway fill:#bbf,stroke:#333,stroke-width:2px
100
100
```
@@ -168,15 +168,15 @@ graph TB
168
168
VS --> AuthZ[Authorization Policy]
169
169
AuthZ --> Gateway[MCP Gateway Pod]
170
170
end
171
-
171
+
172
172
Gateway --> MCP1[MCP Server Pod 1]
173
173
Gateway --> MCP2[MCP Server Pod 2]
174
-
174
+
175
175
OIDC[OIDC Provider] -.->|JWT Validation| AuthZ
176
176
end
177
-
177
+
178
178
User[User] -->|HTTPS + JWT| IG
179
-
179
+
180
180
style AuthZ fill:#f96,stroke:#333,stroke-width:2px
181
181
style Gateway fill:#bbf,stroke:#333,stroke-width:2px
182
182
```
@@ -271,13 +271,13 @@ graph LR
271
271
Plugin[OIDC Plugin] --> Route[Route]
272
272
Route --> Service[Service]
273
273
end
274
-
274
+
275
275
User[User] -->|HTTPS| Plugin
276
276
Service -->|X-Consumer-Username| Gateway[MCP Gateway]
277
277
Gateway --> MCP[MCP Servers]
278
-
278
+
279
279
Plugin -.->|OIDC Flow| IDP[Keycloak/Auth0]
280
-
280
+
281
281
style Plugin fill:#f9f,stroke:#333,stroke-width:2px
282
282
style Gateway fill:#bbf,stroke:#333,stroke-width:2px
283
283
```
@@ -345,9 +345,9 @@ PROXY_USER_HEADER=Remote-User
345
345
graph LR
346
346
User[User] -->|HTTPS| CF[Cloudflare Edge]
347
347
CF -->|Cf-Access-Jwt-Assertion| Gateway[MCP Gateway]
348
-
348
+
349
349
CF -.->|SAML/OIDC| IDP[Identity Provider]
350
-
350
+
351
351
style CF fill:#f90,stroke:#333,stroke-width:2px
352
352
style Gateway fill:#bbf,stroke:#333,stroke-width:2px
353
353
```
@@ -389,15 +389,15 @@ graph TB
389
389
WAF[WAF] --> LB[Load Balancer]
390
390
LB --> Proxy[Auth Proxy]
391
391
end
392
-
392
+
393
393
subgraph "Private Network"
394
394
Proxy -->|Internal Only| Gateway[MCP Gateway]
395
395
Gateway --> MCP1[MCP Server 1]
396
396
Gateway --> MCP2[MCP Server 2]
397
397
end
398
-
398
+
399
399
Internet[Internet] -->|HTTPS| WAF
400
-
400
+
401
401
style Proxy fill:#f96,stroke:#333,stroke-width:2px
402
402
style Gateway fill:#bbf,stroke:#333,stroke-width:2px
403
403
```
@@ -465,7 +465,7 @@ Configure your load balancer to use these endpoints:
465
465
466
466
??? question "Getting 401 Unauthorized with proxy headers"
467
467
** Check these settings:**
468
-
468
+
469
469
1. Verify `MCP_CLIENT_AUTH_ENABLED=false`
470
470
2. Ensure `TRUST_PROXY_AUTH=true`
471
471
3. Confirm header name matches `PROXY_USER_HEADER`
@@ -481,15 +481,15 @@ Configure your load balancer to use these endpoints:
481
481
```
482
482
WARNING - MCP client authentication is disabled but trust_proxy_auth is not set
483
483
```
484
-
484
+
485
485
**Solution:** Set `TRUST_PROXY_AUTH=true` to acknowledge proxy authentication.
486
486
487
487
??? question "WebSocket connections fail"
488
488
** Common causes:**
489
-
489
+
490
490
1. Proxy not passing headers on WebSocket upgrade
491
491
2. Missing WebSocket support in proxy
492
-
492
+
493
493
**nginx fix:**
494
494
```nginx
495
495
location /ws {
@@ -503,13 +503,13 @@ Configure your load balancer to use these endpoints:
503
503
504
504
??? question "How to handle multiple authentication methods?"
505
505
** Use virtual servers with different auth configs:**
506
-
506
+
507
507
```yaml
508
508
# Server 1: Proxy auth
509
509
- name: internal-server
510
510
auth_mode: proxy
511
511
proxy_header: X-Employee-Id
512
-
512
+
513
513
# Server 2: JWT auth
514
514
- name: external-server
515
515
auth_mode: jwt
@@ -526,17 +526,17 @@ graph LR
526
526
A1[Document Current Auth] --> A2[Deploy Proxy]
527
527
A2 --> A3[Test Proxy Auth]
528
528
end
529
-
529
+
530
530
subgraph "Phase 2: Dual Mode"
531
531
B1[Enable Both Auth] --> B2[Migrate Clients]
532
532
B2 --> B3[Monitor Logs]
533
533
end
534
-
534
+
535
535
subgraph "Phase 3: Proxy Only"
536
536
C1[Disable JWT Auth] --> C2[Remove JWT Code]
537
537
C2 --> C3[Document Change]
538
538
end
539
-
539
+
540
540
A3 --> B1
541
541
B3 --> C1
542
542
```
@@ -547,7 +547,7 @@ graph LR
547
547
```bash
548
548
# Deploy auth proxy alongside existing setup
549
549
docker-compose up -d oauth2-proxy
550
-
550
+
551
551
# Test proxy authentication
552
552
curl -H "Authorization: Bearer $TOKEN" \
553
553
http://localhost:4180/health
@@ -566,7 +566,7 @@ graph LR
566
566
# Test JWT (existing)
567
567
curl -H "Authorization: Bearer $JWT_TOKEN" \
568
568
http://localhost:4444/tools
569
-
569
+
570
570
# Test proxy header (new)
571
571
curl -H "X-Auth-Request-Email: [email protected] " \
572
572
http://localhost:4444/tools
@@ -577,7 +577,7 @@ graph LR
577
577
# Disable JWT authentication
578
578
MCP_CLIENT_AUTH_ENABLED=false
579
579
TRUST_PROXY_AUTH=true
580
-
580
+
581
581
# Restart gateway
582
582
docker-compose restart mcp-gateway
583
583
```
@@ -594,12 +594,12 @@ graph LR
594
594
Cache -->|Miss| IDP1[IDP]
595
595
IDP1 --> Cache
596
596
end
597
-
597
+
598
598
subgraph "Without Caching"
599
599
Proxy2[Auth Proxy] --> IDP2[IDP]
600
600
IDP2 --> Gateway2[MCP Gateway]
601
601
end
602
-
602
+
603
603
style Cache fill:#9f9,stroke:#333,stroke-width:2px
604
604
```
605
605
@@ -665,4 +665,4 @@ SESSION_TTL=3600 # 1 hour
665
665
- [ Authentication Overview] ( ../authentication.md )
666
666
- [ Security Best Practices] ( ../security.md )
667
667
- [ Deployment Guide] ( ../deployment/index.md )
668
- - [ Federation Setup] ( ../federation.md )
668
+ - [ Federation Setup] ( ../federation.md )
0 commit comments