docs: rename diagram assets to doc-prefixed scheme, update exports

Asset renames (matching the new Nextcloud source naming convention —
doc name first, then description):
- architecture-trust-depth.svg -> architecture-overview-trust-depth.svg
- firewall-docker-bypass.svg -> firewall-and-network-docker-bypass.svg
- secrets-lifecycle.svg -> secrets-and-pki-lifecycle.svg
- trust-boundaries-blast-radius.svg -> readme-trust-boundaries-blast-radius.svg
Updated all 4 markdown references accordingly.

Also refreshed diagram exports (secret-distribution-flows.svg, and the
4 renamed ones) with today's fixes, and folded in the earlier pending
sso-and-identity.md work: precise live-verified native-OIDC app list
(12 apps, not ~9), the Proxmox no-Proxy-Provider exception, real API
evidence for it, and the automation-bot migration story.
This commit is contained in:
thesabear committed 2026-08-27 23:48:41 +03:00
1 parent 426ef7f133
commit a9518c5381
13 files changed
+33 -20

No files matched your search

+16 -3
View File
@@ -9,7 +9,7 @@ A homelab with dozens of self-hosted apps means dozens of different auth impleme
The proxy layer earns its own keep on top of that, though — it protects apps that don't have a login of their own at all. Not every self-hosted tool ships with real authentication; some are built assuming they'll only ever be reached from an already-trusted network and skip it entirely. Registering a Proxy Provider in front of an app like that puts Authentik's forward-auth check at the reverse-proxy hop, before the request ever reaches the app itself — so an app with zero security of its own still sits behind a real login, enforced by something other than the app. For apps that already have native OIDC, the proxy layer isn't doing the authenticating (the app does its own token exchange) — but for everything else, it's the only auth check that exists, period.
Every app gets the Proxy Provider registration described above — no exceptions, that's the universal baseline. A handful of apps get a second, additional layer on top of it: real native OIDC/SAML support for their own login page, used *alongside* the Proxy Provider rather than replacing it:
Every app gets the Proxy Provider registration described above — that's the universal baseline, with exactly one real exception found by checking live rather than assuming: Proxmox itself has no Proxy Provider at all, confirmed absent from Authentik's own API. It runs on native OIDC only — unlike its sibling PBS, which has both. A handful of other apps get a second, additional layer on top of the Proxy Provider baseline: real native OIDC/SAML support for their own login page, used *alongside* it rather than replacing it. The table below is pulled from Authentik's API directly, not from memory of what was set up — each provider's actual model type, not just its name:
| App | Stack |
|---|---|
@@ -20,10 +20,23 @@ Every app gets the Proxy Provider registration described above — no exceptions
| Grafana | [`stacks/platform/grafana-stack/`](../stacks/platform/grafana-stack/) |
| Audiobookshelf | [`stacks/media/audiobookshelf/`](../stacks/media/audiobookshelf/) |
| Dockhand | [`stacks/platform/dockhand/`](../stacks/platform/dockhand/) |
| Proxmox / PBS | hypervisor-level, not a docker stack |
| Firefly III | [`stacks/productivity/firefly-iii/`](../stacks/productivity/firefly-iii/) |
| Seerr | [`stacks/media/seerr/`](../stacks/media/seerr/) |
| Proxmox / PBS | hypervisor-level, not a docker stack — PBS has both layers, Proxmox has native OIDC only |
Every other app runs on the Proxy Provider alone — which, per the point above, is never a weaker path: it's the same forward-auth check either way, just without a second, app-native login layered on top of it.
This is the actual live query against Authentik's API, not a paraphrase of what's assumed to be configured:
```
$ curl -s -H "Authorization: Bearer [REDACTED]" \
"https://authentik.[service-to-service zone]/api/v3/providers/proxy/?page_size=1" | jq '.pagination.count'
96
$ curl -s -H "Authorization: Bearer [REDACTED]" \
"https://authentik.[service-to-service zone]/api/v3/providers/proxy/?page_size=200" | jq -r '.results[].name' | grep -E '^proxmox'
[no output — Proxmox has no Proxy Provider at all]
```
> [!TIP]
> **Removal is a real, deliberate step, not an afterthought.** Decommissioning an app means deleting the Application (by slug), then the Proxy Provider, then detaching that provider from the outpost's own provider list, then removing its icon file — in that order. Skipping the outpost-detach step is the easy mistake: the Application and Provider both look gone, but the outpost still references a provider that no longer resolves to anything, and that orphaned reference doesn't surface as an error anywhere obvious.
@@ -47,7 +60,7 @@ So an app's OIDC discovery/authority setting always points at the service-to-ser
## Git access: least privilege, not the admin account
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."
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. This wasn't the original setup: automated pushes used to run through the personal admin account used for interactive access, the same one with full admin rights over the Git server. That got fixed by standing up a separate account with its own SSH keypair and adding it as a write collaborator on every repo it touches — routine automated commits no longer run under an admin credential at all. 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."
![Gitea repo collaborators: automation-bot with Write access, not an admin account](../assets/gitea-collaborators-automation-bot.png)