From a86fca4d9a0a8707f97b6b5efdc94ba54dcc16cb Mon Sep 17 00:00:00 2001
From: mo khan <mo@mokhan.ca>
Date: Thu, 27 Mar 2025 14:06:32 -0600
Subject: docs: add sequence diagram for OIDC Protocol Flow

---
 doc/share/authz/DESIGN.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(limited to 'doc/share/authz')

diff --git a/doc/share/authz/DESIGN.md b/doc/share/authz/DESIGN.md
index c64386e..cdeb5ff 100644
--- a/doc/share/authz/DESIGN.md
+++ b/doc/share/authz/DESIGN.md
@@ -74,6 +74,31 @@ UI --> Browser: Return list of projects as HTML
 
 OIDC Login Flow
 
+```plantuml
+@startuml
+Browser -> UI: Get dashboard
+UI --> Browser: Generate OAuth Grant Request and redirect to IdP
+
+Browser -> IdP: Deliver OAuth Grant Request
+IdP --> Browser: Redirect to Login Page
+Browser -> IdP: Login
+IdP --> Browser: Generate Consent Screen for Authorization Code flow
+Browser -> IdP: Consent
+IdP --> Browser: Generate Authorization Code and redirect to UI
+
+Browser -> UI: Deliver Authorization Code Grant
+UI -> IdP: Exchange Authorization Code Grant for Tokens
+IdP --> UI: Return `access_token` and `refresh_token`
+UI --> Browser: Redirect to dashboard
+Browser -> UI: Get dashboard
+UI -> API: Request list of projects and provide Access Token
+API -> IdP: Check if token is valid and check declarative policy
+IdP --> API: Return result of `Ability.allowed?`
+API --> UI: Return list of projects as JSON
+UI --> Browser: Return list of projects as HTML
+@enduml
+```
+
 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`
-- 
cgit v1.2.3