Envoy Gateway Architecture Diagrams

Posted by     "赵化冰" on Monday, May 12, 2025

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

ApplicationAuthorization ServerEnvoyUser-Agent (Browser)User (End User)ApplicationAuthorization ServerEnvoyUser-Agent (Browser)User (End User)alt[user authenticated][user not authenticated]alt[no valid token][valid token]Open https://myapp.example.comHTTP GET / Host: myapp.example.comvalidate access and id token in cookie using HMACgenerate csrf_token and stategenerate code_verifier and code_challengeHTTP 302 Redirect to Authorization Server with csrf_token and code_challenge in cookiesAuthorization requestRedirect to user login pageSubmit user credentialsUser login requestRedirect to callback with authorization codeAuthorization code callback with csrf_token in cookievalidate csrf_token in the state against the one in cookieToken request with code_verifierAccess token (+ id token + refresh token)HTTP 302 Redirect to original URL with access and id token in cookiesHTTP GET / Host: myapp.example.com with access and id token in cookiesForward request with user identity in headerResponseResponseRedirect to login page with errorForward request with user identity in headerResponseResponse

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:

Authorization ServerMCP Server2MCP Server1MCP Gateway (Resource Server)ClientUser-Agent (Browser)Authorization ServerMCP Server2MCP Server1MCP Gateway (Resource Server)ClientUser-Agent (Browser)Extract resource_metadata URL from WWW-AuthenticateParse metadata and extract authorization server(s)Client determines AS to usealt[Dynamic client registration]Generate PKCE parametersInclude resource parameterUser authorizesWe can implment fine-grained access control hereMCP communication continues with valid tokenMCP communication continues with valid tokenMCP request without tokenHTTP 401 Unauthorized with WWW-Authenticate headerRequest Protected Resource MetadataReturn metadataGET /.well-known/oauth-authorization-serverAuthorization server metadata responsePOST /registerClient CredentialsOpen browser with authorization URL + code_challenge + resourceAuthorization request with resource parameterRedirect to callback with authorization codeAuthorization code callbackToken request + code_verifier + resourceAccess token (+ refresh token)MCP request with access tokenverify the access tokenMCP requestMCP responseMCP responseMCP request with access tokenMCP requestMCP responseMCP response