thesabear
e2765ba749
The source material says header-based forward-auth is 'the viable path instead, if SSO is wanted for an app like this' - conditional contingency guidance for a scenario that may not have actually come up, not a description of something built and running. Presenting it as live, deployed behavior in both docs/sso-and-identity.md and the README was a real accuracy error. Removed from both; the doc still covers what's actually confirmed (Authentik, dual-zone registration, native OIDC vs. proxy forward-auth split, least-privilege Git access).
51 lines
4.1 KiB
Markdown
51 lines
4.1 KiB
Markdown
# 🪪 SSO & Identity
|
|
|
|
> [!NOTE]
|
|
> Authentik is the identity provider for this fleet — self-hosted rather than an external IdP, for the same reason Vault is self-hosted in [`docs/secrets-and-pki.md`](secrets-and-pki.md): internal-only apps shouldn't need to trust a third party just to authenticate a login, and the two-zone reverse-proxy model in [`docs/dns-naming.md`](dns-naming.md) only works if the identity provider itself lives inside that same trust boundary.
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Software** | Authentik, self-hosted |
|
|
| **Pattern** | Provider + application pair registered once per reverse-proxy zone an app is exposed on |
|
|
| **Native OIDC/SAML apps** | ~12 apps, where the upstream software supports it directly |
|
|
| **Everything else** | Proxy-based forward-auth — SSO without the app needing to implement OIDC itself |
|
|
|
|
## Why proxy-based forward-auth, not just native OIDC everywhere
|
|
|
|
Most self-hosted apps don't implement OIDC or SAML themselves — a media manager or a bookmarking tool typically wasn't built with enterprise SSO in mind. Requiring native OIDC support fleet-wide would have meant leaving most apps without SSO at all. Authentik's proxy-provider forward-auth pattern sits in front of any app regardless of whether it understands OIDC, checking authentication at the reverse-proxy layer before a request ever reaches the app itself. The ~12 apps that *do* support native OIDC still use it — it's a better experience where available (no separate login redirect through the proxy) — but forward-auth is what makes SSO actually fleet-wide rather than limited to whichever apps happen to support it.
|
|
|
|
## Login flow — same shape, every app
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as User
|
|
participant App as App (browser-facing zone)
|
|
participant IdP as Authentik (internal zone)
|
|
|
|
U->>App: Opens app
|
|
App->>U: Redirect to Authentik
|
|
U->>IdP: OAuth authorize/token exchange
|
|
Note over IdP: Always happens on the internal zone,<br/>even though the app itself lives<br/>on the browser-facing zone
|
|
IdP->>U: Success
|
|
U->>App: Lands back on the app
|
|
```
|
|
|
|
This split matters more than it looks: the browser-facing zone enforces mutual TLS (see [`docs/dns-naming.md`](dns-naming.md)) and the app itself might live there, but the actual authentication handshake always happens against Authentik's internal-zone address. Getting this backwards — pointing the OIDC discovery/authority setting at the wrong zone — is a real, easy mistake when onboarding a new app, since the app's own login page is on the *other* zone and it's natural to assume the auth endpoint matches.
|
|
|
|
Every app-specific setting beyond this shape (token lifetime, scopes, flow type) is deliberately **not** generalized across apps — each app's own OIDC documentation gets read fresh rather than copying another app's provider config, since the details genuinely differ per vendor and copying blind is how subtle auth bugs get introduced.
|
|
|
|
## Git access: least privilege, not the admin account
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
CI["CI / Orchestration engine<br/>see docs/orchestration.md"] -->|scoped write| Bot["Dedicated bot account<br/>non-admin"]
|
|
Bot --> Repo["Gitea"]
|
|
Other["Other hosts"] -->|read-only| Deploy["Deploy keys<br/>per host"]
|
|
Deploy --> Repo
|
|
```
|
|
|
|
This is a smaller decision than the SSO model above, but the same principle: automation should never run with more privilege than it needs. CI and orchestration pushes (the flows described in [`docs/orchestration.md`](orchestration.md)) run through a dedicated, non-admin bot account with scoped write access — never through an administrator identity. Hosts that only need to *read* get separate read-only deploy keys instead of any shared credential. The practical payoff: if an automation credential ever leaks, the blast radius is "can push to specific repos," not "has full admin control of the Git server."
|
|
|
|
---
|
|
Related: [`docs/dns-naming.md`](dns-naming.md), [`docs/orchestration.md`](orchestration.md), [`docs/secrets-and-pki.md`](secrets-and-pki.md) · Stacks: [`stacks/identity-and-security/authentik/`](../stacks/identity-and-security/authentik/), [`stacks/platform/gitea/`](../stacks/platform/gitea/)
|