From ce31ca617a318ab1a035f2693c576b512b067efa Mon Sep 17 00:00:00 2001
From: mo khan <mo@mokhan.ca>
Date: Thu, 27 Mar 2025 13:49:38 -0600
Subject: docs: add steps for building sequence diagrams for different types of
 flows

---
 doc/share/authz/DESIGN.md | 63 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/doc/share/authz/DESIGN.md b/doc/share/authz/DESIGN.md
index 8bf5347..16134fe 100644
--- a/doc/share/authz/DESIGN.md
+++ b/doc/share/authz/DESIGN.md
@@ -4,7 +4,66 @@
 
 ## Proposed
 
-### Option 1
+### Architecture
+
+```plaintext
+ -------------
+ | user-agent |
+ -------------
+       |
+       V
+----|:8080|-----------------------------------------------
+       |
+       V
+ ---------------
+ | API Gateway |
+ ---------------
+        |
+        |    --------------------
+        |--->| IdP (saml, oidc) |
+        |    --------------------
+        |    | :http   | :grpc  |
+        |    --------------------
+        |        A         A
+   -----------   |         |
+   |         |   |         |
+   V         V   |         |
+ ------    ------------    |
+ | UI |    | REST API |----|
+ ------    ------------
+
+[UI]: ui.example.com
+[REST API]: api.example.com
+[IdP]: idp.example.com
+```
+
+SAML Login Flow
+
+1. `GET http://ui.example.com/saml/new`
+1. `POST http://idp.example.com/saml/new`
+1. `GET http://idp.example.com/sessions/new?redirect_back=/saml/continue`
+1. `POST http://idp.example.com/sessions`
+1. `GET http://idp.example.com/saml/continue`
+1. `POST http://ui.example.com/saml/assertions`
+1. `POST http://idp.example.com/oauth/token`
+1. `GET http://api.example.com/groups.json`
+1. `GET grpc://idp.example.com/twirp/authx.rpc.Ability/Allowed`
+
+OIDC Login Flow
+
+1. `GET http://ui.example.com/oidc/new`
+1. `GET http://idp.example.com/oauth/authorize`
+1. `GET http://idp.example.com/sessions/new?redirect_back=/oauth/authorize/continue`
+1. `POST http://idp.example.com/sessions`
+1. `GET http://idp.example.com/oauth/authorize/continue`
+1. `POST http://idp.example.com/oauth/authorize`
+1. `GET http://ui.example.com/oauth/callback`
+1. `POST http://idp.example.com/oauth/token`
+1. `GET http://api.example.com/groups.json`
+1. `GET grpc://idp.example.com/twirp/authx.rpc.Ability/Allowed`
+
+### Permissions
+#### Option 1
 
 | permission | scope                                                                         | description                                         |
 | ---------- | -----                                                                         | -----------                                         |
@@ -33,7 +92,7 @@ The following example allows the subject of the token to read all of the descend
 }
 ```
 
-### Option 2
+#### Option 2
 
 Encode access and scope directly into the name of the permission.
 
-- 
cgit v1.2.3