Oftentimes, I find myself spending a lot of time jumping between different files to understand the codebase while reviewing a PR or writing a new feature — even when I originally wrote a good chunk of that code myself.
In this sense, human brain feels like an old computer with just 64K of RAM. It’s constantly swapping data in and out because there just isn’t enough memory. Before it can do any serious work, it has to reload all the context back into memory — a slow and sometimes frustrating process, especially when you’re doing it over and over.
On the flip side, our brains are really good at understanding the big picture — and that’s where diagrams shine. So I put these together to help myself quickly get a clearer picture of Envoy Gateway’s architecture whenever I’m reviewing a PR or building something new.
If you’re trying to understand how Envoy Gateway works under the hood, you might find them useful too.
I’ll keep updating this post to include more diagrams.
Overview
Envoy OAuth Code Flow
sequenceDiagram
participant U as User (End User)
participant B as User-Agent (Browser)
participant E as Envoy
participant A as Authorization Server
participant P as Application
U->>B: Open https://myapp.example.com
B->>E: HTTP GET / Host: myapp.example.com
E->>E: validate access and id token in cookie using HMAC
alt no valid token
E->>E: generate csrf_token and state
E->>E: generate code_verifier and code_challenge
E->>B: HTTP 302 Redirect to Authorization Server with csrf_token and code_challenge in cookies
B->>A: Authorization request
A->>B: Redirect to user login page
U->>B: Submit user credentials
B->>A: User login request
alt user authenticated
A->>B: Redirect to callback with authorization code
B->>E: Authorization code callback with csrf_token in cookie
E->>E: validate csrf_token in the state against the one in cookie
E->>A: Token request with code_verifier
A->>E: Access token (+ id token + refresh token)
E->>B: HTTP 302 Redirect to original URL with access and id token in cookies
B->>E: HTTP GET / Host: myapp.example.com with access and id token in cookies
E->>P: Forward request with user identity in header
P-->>E: Response
E-->>B: Response
else user not authenticated
A->>B: Redirect to login page with error
end
else valid token
E->>P: Forward request with user identity in header
P-->>E: Response
E-->>B: Response
end
AI Gateway MCP Auth Flow
Enable centralized access control at the gateway for backend MCP servers that do not natively support the MCP authorization spec:
sequenceDiagram
participant B as User-Agent (Browser)
participant C as Client
participant G as MCP Gateway (Resource Server)
participant M1 as MCP Server1
participant M2 as MCP Server2
participant A as Authorization Server
C->>G: MCP request without token
G->>C: HTTP 401 Unauthorized with WWW-Authenticate header
Note over C: Extract resource_metadata URL from WWW-Authenticate
C->>G: Request Protected Resource Metadata
G->>C: Return metadata
Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use
C->>A: GET /.well-known/oauth-authorization-server
A->>C: Authorization server metadata response
alt Dynamic client registration
C->>A: POST /register
A->>C: Client Credentials
end
Note over C: Generate PKCE parameters<br/>Include resource parameter
C->>B: Open browser with authorization URL + code_challenge + resource
B->>A: Authorization request with resource parameter
Note over A: User authorizes
A->>B: Redirect to callback with authorization code
B->>C: Authorization code callback
C->>A: Token request + code_verifier + resource
A->>C: Access token (+ refresh token)
C->>G: MCP request with access token
G->>G: verify the access token
Note over G,G: We can implment fine-grained access control here
G->>M1: MCP request
M1-->>G: MCP response
G-->>C: MCP response
Note over C,G: MCP communication continues with valid token
C->>G: MCP request with access token
G->>M2: MCP request
M2-->>G: MCP response
G-->>C: MCP response
Note over C,G: MCP communication continues with valid token