From f68f93af645b1caa7fbd729d18e699e90f3a5e6a Mon Sep 17 00:00:00 2001 From: thesabear Date: Fri, 28 Aug 2026 00:17:29 +0300 Subject: [PATCH] docs: add OIDC cross-zone redirect diagram to sso-and-identity.md Sequence diagram showing the browser carries every hop itself - Authentik and the app never talk directly - with only the OAuth authorize/token exchange crossing from the browser-facing zone into the service-to-service zone. Built to the public-repo diagram conventions in CLAUDE.md (labelBackgroundColor + matching rich-text span, off-line label positioning, line-color-matched labels, legend instead of a color-explaining caption). --- assets/sso-and-identity-oidc-cross-zone-redirect.svg | 4 ++++ docs/sso-and-identity.md | 2 ++ 2 files changed, 6 insertions(+) create mode 100644 assets/sso-and-identity-oidc-cross-zone-redirect.svg diff --git a/assets/sso-and-identity-oidc-cross-zone-redirect.svg b/assets/sso-and-identity-oidc-cross-zone-redirect.svg new file mode 100644 index 0000000..d096fcd --- /dev/null +++ b/assets/sso-and-identity-oidc-cross-zone-redirect.svg @@ -0,0 +1,4 @@ + + + +
BROWSER-FACING ZONE — *.local.thesabear.net
SERVICE-TO-SERVICE ZONE — *.caddy.thesabear.net (no mTLS on this hop)
Browser
App
Authentik
1. User opens app
2. App's response: redirect to Authentik
3. Browser follows it — OAuth authorize/token exchange, crossing into the caddy zone
4. Authentik's response: success, redirect back
5. Browser lands back on the app — still the local zone
Gray — stays within a single zone
Orange — the one hop that crosses into the service-to-service zone
Every hop is carried by the browser itself — Authentik and the app never talk to each other directly. Every app's OIDC discovery/authority setting points at the caddy zone for exactly this reason, even though the app itself always lives on the local zone.
 \ No newline at end of file diff --git a/docs/sso-and-identity.md b/docs/sso-and-identity.md index b5eb710..3c47f73 100644 --- a/docs/sso-and-identity.md +++ b/docs/sso-and-identity.md @@ -53,6 +53,8 @@ For an app using native OIDC, the login always follows the same path: 3. That exchange happens against Authentik's own address on the **service-to-service zone** — reachable from a browser for this one hop specifically, even though that zone doesn't get the mutual-TLS treatment the browser-facing zone does. 4. On success, the browser lands back on the app, still on the browser-facing zone. +![OIDC cross-zone redirect: the browser carries every hop itself — Authentik and the app never talk to each other directly — with only the OAuth authorize/token exchange ever crossing from the browser-facing zone into the service-to-service zone](../assets/sso-and-identity-oidc-cross-zone-redirect.svg) + So an app's OIDC discovery/authority setting always points at the service-to-service zone, even though the app itself is normally reached on the browser-facing zone — the two zones are defined in [`docs/dns-naming.md`](dns-naming.md). This is confirmed against one real app's actual login flow, not assumed to hold for every app without checking. Every other app-specific setting (token lifetime, scopes, flow type) doesn't generalize the same way — each app's own OIDC documentation gets read fresh rather than copying another app's provider config, since those details genuinely differ per vendor. > [!NOTE]