Skip to content

Commit f6ab2e1

Browse files
aarora79aarora79
committed
auth flow documentation
1 parent a3d543f commit f6ab2e1

File tree

2 files changed

+226
-7
lines changed

2 files changed

+226
-7
lines changed

‎docker/nginx_rev_proxy.conf

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@ server {
33
listen 80;
44
server_name mcpgateway localhost mcpgateway.ddns.net ec2-18-205-158-118.compute-1.amazonaws.com;
55

6-
6+
# Add this to trigger the named location for 403 errors
7+
error_page 403 = @forbidden_error;
8+
79
# Route for Cost Explorer service
810
location / {
911
proxy_pass http://127.0.0.1:7860/;
@@ -108,11 +110,12 @@ server {
108110
}
109111

110112
location @forbidden_error {
113+
default_type application/json;
111114
return 403 '{"error": "Access forbidden"}';
112-
add_header Content-Type application/json;
113-
add_header Connection close;
115+
add_header Content-Type application/json always;
116+
add_header Connection close always;
114117
}
115-
118+
116119
error_log /var/log/nginx/error.log debug;
117120
}
118121

@@ -129,7 +132,9 @@ server {
129132
# Stronger cipher suite
130133
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
131134

132-
135+
# Add this to trigger the named location for 403 errors
136+
error_page 403 = @forbidden_error;
137+
133138
# Auth validation endpoint - passes entire request to auth server
134139
location = /validate {
135140
internal;
@@ -225,9 +230,10 @@ server {
225230
}
226231

227232
location @forbidden_error {
233+
default_type application/json;
228234
return 403 '{"error": "Access forbidden"}';
229-
add_header Content-Type application/json;
230-
add_header Connection close;
235+
add_header Content-Type application/json always;
236+
add_header Connection close always;
231237
}
232238

233239
error_log /var/log/nginx/error.log debug;

‎docs/auth.md

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Authentication and Authorization Enhancements for MCP
2+
3+
Authorization in context of MCP usually refers to two distinct flows or grant types:
4+
5+
- Agent acting on-behalf of a user: in this case the Agent takes the identity of the end-user (human). For example, an Agent invoked by an application as a result of a user asking a question in a chatbot will use the user's identity for authentication and authorization.
6+
7+
- Agent acting on its own behalf: in this case the Agent gets invoked automatically in response to an event and thus the Agent has its own identity. For example a network remediation agent that gets invoked when a network anomaly is detected will have an identity of its own as it is not being invoked by a user.
8+
9+
The latest MCP authorization spec available [here](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) discusses this in context of OAuth Grant types.
10+
11+
## The challenge with MCP auth in an enterprise scenario
12+
13+
The current MCP spec puts the onus of authentication on the MCP server i.e. the server is responsible for providing access credentials to the MCP client as well as validating those credentials (see [OAuth for model context protocol](https://aaronparecki.com/2025/04/03/15/oauth-for-model-context-protocol) for an illustrative explanation). This implies that developers now have to add Auth capabilities in their MCP servers and in an enterprise scenario with hundreds of MCP servers and thousands of tools this is a huge challenge. The problem is compounded by the fact that enterprises would want to offer fine-grained access controls to tools (an Agent can access the server but only a subset of the tools provided by the server) for both the types of Agent flows described above.
14+
15+
## A Solution with an MCP Gateway and Registry
16+
17+
The MCP gateway and Registry provides an enterprise ready solution that integrates with an IdP and provides a separate auth server which handles all authorization and authentication by talking to an IdP and this frees up the MCP servers from having to handle any authentication.
18+
19+
Here is an architecture diagram of the system.
20+
21+
```mermaid
22+
graph LR
23+
%% AI Agent
24+
Agent[AI Agent]
25+
26+
%% Identity Provider
27+
IdP[Identity Provider]
28+
29+
%% Gateway and Registry Block
30+
subgraph GwReg["Gateway & Registry"]
31+
Gateway["Gateway<br/>(Reverse Proxy)"]
32+
Registry[Registry]
33+
AuthServer["Auth Server"]
34+
end
35+
36+
%% MCP Server Farm
37+
subgraph MCPFarm["MCP Server Farm"]
38+
MCP1[MCP Server 1]
39+
MCP2[MCP Server 2]
40+
MCP3[MCP Server 3]
41+
MCPn[MCP Server n]
42+
end
43+
44+
%% Connections
45+
Agent -->|Discover servers/tools| Registry
46+
Agent -->|Data plane requests| Gateway
47+
Gateway -->|Auth verification| AuthServer
48+
Gateway -->|Proxy requests| MCP1
49+
Gateway -->|Proxy requests| MCP2
50+
Gateway -->|Proxy requests| MCP3
51+
Gateway -->|Proxy requests| MCPn
52+
53+
%% Auth flow
54+
IdP -.->|Identity/tokens| Agent
55+
AuthServer -.->|Validate tokens| IdP
56+
57+
%% Styling
58+
classDef agentStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
59+
classDef idpStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
60+
classDef gwregStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
61+
classDef mcpStyle fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
62+
63+
class Agent agentStyle
64+
class IdP idpStyle
65+
class Gateway,Registry,AuthServer gwregStyle
66+
class MCP1,MCP2,MCP3,MCPn mcpStyle
67+
```
68+
69+
At a high-level the flow works as follows:
70+
71+
```mermaid
72+
sequenceDiagram
73+
participant User
74+
participant Agent as Agent<br/>(includes MCP client)
75+
participant IdP as Enterprise IdP
76+
77+
box rgba(0,0,0,0) MCP Gateway & Registry Solution
78+
participant Gateway as Gateway<br/>(Reverse Proxy)
79+
participant AuthServer as Auth Server
80+
participant Registry as Registry<br/>MCP Server
81+
end
82+
83+
participant MCP as External<br/>MCP Server
84+
85+
%% Step 1: Get credentials
86+
Note over User,IdP: Step 1: Credential Acquisition (Choose One)
87+
alt Agent Identity
88+
Agent->>IdP: Request auth credentials
89+
IdP->>Agent: Return credentials + metadata
90+
else On-behalf of User
91+
User->>IdP: Sign-in (web/CLI)
92+
IdP->>User: Return credentials + metadata
93+
User->>Agent: Provide credentials
94+
end
95+
96+
%% Step 2: Embed credentials in headers
97+
Note over Agent: Step 2: Embed credentials + IdP metadata
98+
99+
%% Step 3: Tool Discovery with scoped access
100+
Note over Agent,Registry: Step 3: Scoped Tool Discovery
101+
Agent->>Gateway: Tool discovery request with auth headers
102+
Gateway->>AuthServer: Validate credentials
103+
AuthServer->>IdP: Verify credentials
104+
IdP->>AuthServer: Auth response + scope
105+
AuthServer->>Gateway: 200 OK + allowed scopes
106+
Gateway->>Registry: Tool discovery request + scope headers
107+
108+
Note over Registry: Registry filters tools based<br/>on Agent's allowed scopes
109+
Registry->>Gateway: Filtered tool list (only accessible tools)
110+
Gateway->>Agent: Available tools response
111+
112+
%% Step 4: MCP Tool Invocation to External Server
113+
Note over Agent,MCP: Step 4: MCP Tool Invocation Flow
114+
Agent->>Gateway: MCP tool call request with auth headers
115+
Gateway->>AuthServer: Validate credentials + scope
116+
AuthServer->>IdP: Verify credentials
117+
IdP->>AuthServer: Auth response + scope
118+
119+
alt Valid credentials + sufficient scope
120+
AuthServer->>Gateway: 200 OK + allowed scopes
121+
Gateway->>MCP: Forward MCP request
122+
MCP->>Gateway: MCP response
123+
Gateway->>Agent: MCP response
124+
else Invalid or insufficient access
125+
AuthServer->>Gateway: 403 Access Denied
126+
Gateway->>Agent: 403 Access Denied
127+
end
128+
129+
%% Footnotes
130+
Note over Agent,MCP: Notes:<br/>• Agent can skip tool discovery and call MCP methods directly<br/>• Auth validation flow remains the same for all MCP operations<br/> (initialize, tools/call with tool-specific scope validation)
131+
```
132+
133+
1. An Agent gets auth credentials from an enterprise IdP either by itself (agent identity) or is provided these credentials (on-behalf of user's identity) that have been retrieved by the (human) user through a separate program (such as signing-in via a web browser or a CLI command).
134+
135+
1. The Agent embeds these credentials and other metadata needed to verify these credentials in HTTP headers for the MCP protocol messages exchanged with the MCP servers.
136+
137+
1. The MCP servers are only accessible through the Gateway (reverse proxy), upon receiving the messages the Gateway hands them off to an auth server which validates the credentials embedded in the these messages with the enterprise IdP. This validation includes both authentication as well as authorization. The auth server retrieves the access scope for the Agent from the IdP auth validation response and then compares it with the MCP method (`initialize`, `tools/call` etc.) and tool being requested. The auth server responds with a 200 OK if the access should be allowed based on the credentials provided and the scope requested or a an HTTP 403 access denied otherwise. The auth server also includes the list of allowed scopes in its 200 OK response.
138+
139+
1. The Gateway then proceeds to pass on the request to the MCP server to which the request was addressed to in case the access was allowed (200 OK from the auth server) or sends the 403 access denied to the Agent.
140+
141+
1. An Agent uses the same mechanism to talk to the Registry's MCP server for tool discovery. The Agent may request access to a special tool discovery tool available via the Registry's MCP server. The tool discovery tool now has access to the Agent's scope (through the auth server including the scope in the response headers for the 200 OK) and applies the scopes while searching for potential tools that the Agent can have access to, thus it only lists the tools that the Agent has access to in its response via the tool discovery tool. Here is a example scenario, a general purpose AI assistant may be able to discover through the tool finder tool that there is a tool to get the current time at a given location but based on its access it may not have access to a tool to determine stock information and hence the Registry never list the stock information tool as an available tool to the Agent (if the Agent knows about this tool through some out of band mechanism and tries to invoke the tool it would get an access denied as explained in the previous steps).
142+
143+
The above implementation provides an OAuth compliant way to MCP security without the MCP servers being involved in enforcing this security greatly simplifying the MCP server implementation (as compared to every MCP server having to implement authentication and authorization).
144+
145+
146+
## Amazon Cognito based reference implementation (_work in progress_)
147+
148+
This section discusses a reference implementation using Amazon Cognito as the IdP.
149+
150+
### Agent uses on-behalf of identity
151+
152+
### 1. Session Cookie Implementation
153+
154+
The proposed session cookie approach, which encodes user metadata from Cognito, is a valuable addition to our system. However, there are two crucial considerations:
155+
156+
#### a. Out-of-Band Cookie Retrieval
157+
158+
- A separate CLI tool will be required to run before the agent execution.
159+
- Process:
160+
1. CLI opens the browser
161+
2. User authenticates
162+
3. Cookie is retrieved and stored in a local file
163+
4. Agent reads the cookie from the local file
164+
5. Agent uses the cookie in the MCP client
165+
166+
#### b. Validation Server Implementation
167+
168+
- A dedicated Validation Server (Auth Server) will handle cookie validation instead of the Registry.
169+
- Key points:
170+
- Runs in a container, accessible at port 8888
171+
- Performs the same functionality as current `main.py`, `auth`, and related modules
172+
- Triggered by an auth command in the Nginx location section for each server
173+
- Creates a pipeline:
174+
1. Request goes to the Validation Server first
175+
2. If Validation Server returns 200 OK, request proceeds to the MCP server
176+
- MCP server remains unburdened by authentication tasks
177+
178+
#### Advantages:
179+
1. Eliminates need for MCP client in Registry for every client-server communication
180+
2. Maintains Registry as a control plane application
181+
3. Improves scalability
182+
4. Auth server can scale independently in the future
183+
5. Simplifies MCP servers by removing authentication responsibilities
184+
185+
### 2. Machine-to-Machine Authentication
186+
187+
Cognito supports machine-to-machine authentication, enabling Agents to have their own identity separate from user identity.
188+
189+
#### Implementation Details:
190+
- Reference: [AWS Blog on Machine-to-Machine Authentication](https://aws.amazon.com/blogs/mt/configuring-machine-to-machine-authentication-with-amazon-cognito-and-amazon-api-gateway-part-2/)
191+
- Agents are treated as App Clients (Cognito terminology)
192+
- MCP Server(s) function as resource servers
193+
194+
#### Authentication Flow:
195+
1. Agent startup:
196+
- Configured with client ID, client secret, and a set of scopes
197+
- Requests scopes (e.g., MCP Registry with tool finder and basic MCP servers)
198+
2. Cognito issues a JWT token
199+
3. Agent includes the JWT token in MCP headers
200+
4. Auth server on Nginx side:
201+
- Retrieves JWT token
202+
- Calls Cognito to validate token and get allowed scopes
203+
- Returns 200 or 403 based on:
204+
- URL (MCP server)
205+
- Payload (Tools)
206+
- Agent's allowed scopes
207+
208+
#### Advantages:
209+
- Simpler implementation compared to user-based authentication
210+
- Enables fine-grained control over Agent permissions
211+
- Facilitates secure machine-to-machine communication within the MCP ecosystem
212+
213+
By implementing these enhancements, we can significantly improve the security, scalability, and flexibility of our MCP authentication and authorization system.

0 commit comments

Comments
 (0)