docs: add placeholder to model these scenarios

1 files changed, 32 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index bfa2f26..907d53e 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -399,6 +399,38 @@ Envoy Gateway is a control plane that is outside the scope of this document.
 
 ### Authorization Flow
 
+TODO:: model these examples from https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/12#note_2516950269
+
+Example 1: Session cookie
+
+1. Request with a Cookie arrives to Envoy.
+1. Envoy sends the request context to a separate service.
+1. Separate auth service responds with HTTP OK and a token from STS representing the authenticated principal.
+1. Envoy forwards the request to GitLab with the identity token injected into a header.
+
+Example 2: Authorization header
+
+1. Request with an Authorization: Bearer token arrives to Envoy.
+1. Envoy sends the token to a separate service.
+1. Separate service responds with an identity token from STS.
+1. Envoy forwards the request to Rails.
+
+Example 3: Unauthenticated
+
+1. Unauthenticated request arrives.
+1. Envoy forwards the request to Rails without an identity token.
+
+Example 4: Workload Identity Federation
+
+1. OAuth authorization request arrives for 3rd-party integration.
+1. Envoy forwards the request to the authorization server.
+
+Example 5: ?
+
+1. OAuth authorization request arrives for internal service integration.
+1. Envoy forwards the request to the authorization service.
+1. Envoy captures authorization grant and exchanges it for the token (current solution).
+
 ```mermaid
 sequenceDiagram
     participant User