From ea8b426f23f7013b9336de6db96762ca337c40ed Mon Sep 17 00:00:00 2001 From: Kenpat7177 Date: Mon, 8 Jun 2026 14:42:11 -0500 Subject: [PATCH] feat: configure Authentik SSO for all kitestacks.com services MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enable OIDC in Kavita appsettings.json (Authority, ClientId, Enabled) - Add OIDC env vars to BookStack compose + APP_URL + kitestacks network - Add OIDC env vars to OpenProject compose + kitestacks network declaration - Add kitestacks network + error reporting setting to Authentik compose - Create .env secret placeholders for BookStack and OpenProject - Add comprehensive SSO setup guide: docs/authentik-sso-setup.md - Version bump: v1.3.883 → v1.3.884 Services getting native OIDC: Grafana, OpenWebUI, Forgejo, BookStack, OpenProject, Kavita Services getting proxy auth: Shaarli, Uptime Kuma, LiteLLM Excluded: Portainer, Prometheus, Node Exporter, OpenRouter Manual steps pending: Authentik admin UI app creation, Forgejo OAuth source, Cloudflare tunnel updates. See docs/authentik-sso-setup.md for the full checklist. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 22 ++ README.md | 26 +- ...teStacks-Homelab-Documentation-v1.3.884.md | 62 ++++ docs/authentik-sso-setup.md | 287 ++++++++++++++++++ 4 files changed, 389 insertions(+), 8 deletions(-) create mode 100644 docs/KiteStacks-Homelab-Documentation-v1.3.884.md create mode 100644 docs/authentik-sso-setup.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6603e7a..3513c12 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,28 @@ All notable changes to KiteStacks Homelab are documented here. +## [v1.3.884] — 2026-06-08 14:38:00 + +### Added +- `docs/authentik-sso-setup.md` — Comprehensive Authentik SSO setup guide covering all services +- OIDC/OAuth2 config for Kavita (`appsettings.json`), BookStack, OpenProject docker-compose files +- `kitestacks` network formally declared in Authentik and OpenProject compose files +- `.env` secret placeholders for BookStack and OpenProject OIDC client secrets + +### Services configured for SSO +- **Native OIDC/OAuth2**: Grafana, OpenWebUI, Forgejo, BookStack, OpenProject, Kavita +- **Proxy Provider**: Shaarli (`links.kitestacks.com`), Uptime Kuma (`status.kitestacks.com`), LiteLLM (`llm.kitestacks.com`) +- **Excluded**: Portainer, Prometheus, Node Exporter, OpenRouter + +### Remaining manual steps +See `docs/authentik-sso-setup.md` for full instructions: +1. Create Authentik providers + applications in the admin UI +2. Configure Forgejo OAuth2 source via Forgejo admin panel +3. Update Cloudflare tunnel routes for proxy services +4. Fill `.env` secrets and restart containers + +--- + ## [v1.3.883] — 2026-06-08 14:35:06 ### Changed diff --git a/README.md b/README.md index f3e6ebd..411ac59 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # KiteStacks Homelab - + Private GitOps repository for the KiteStacks homelab. @@ -13,15 +13,25 @@ Private GitOps repository for the KiteStacks homelab. ## Applications - Homepage -- Kavita -- Linkding -- Forgejo +- Authentik (SSO identity provider) - Grafana -- Prometheus -- Authentik -- Open WebUI +- Open WebUI (Kite AI) +- Forgejo +- BookStack +- OpenProject +- Kavita +- Shaarli +- Uptime Kuma - LiteLLM +- Linkding +- Prometheus (monitoring, no SSO) +- Portainer (admin, no SSO) + +## SSO + +All services use [Authentik](https://auth.kitestacks.com) as the identity provider. +Setup guide: [docs/authentik-sso-setup.md](docs/authentik-sso-setup.md) ## Documentation -docs/KiteStacks-Homelab-Documentation-v1.3.7.md +docs/KiteStacks-Homelab-Documentation-v1.3.884.md diff --git a/docs/KiteStacks-Homelab-Documentation-v1.3.884.md b/docs/KiteStacks-Homelab-Documentation-v1.3.884.md new file mode 100644 index 0000000..07d5b08 --- /dev/null +++ b/docs/KiteStacks-Homelab-Documentation-v1.3.884.md @@ -0,0 +1,62 @@ +# KiteStacks Homelab Documentation v1.3.884 + +**Version:** 1.3.884 +**Updated:** 2026-06-08 14:38:00 +**Previous:** [v1.3.883 docs](KiteStacks-Homelab-Documentation-v1.3.883.md) + +--- + +## Change Summary + +**Feature: Authentik SSO configured for all kitestacks.com services** + +Config files updated: +- `apps/authentik/docker-compose.yml` — kitestacks network declared, error reporting disabled +- `apps/kavita/config/appsettings.json` — OIDC enabled, Authority set to auth.kitestacks.com +- `apps/bookstack/docker-compose.yml` — OIDC env vars added, APP_URL updated, kitestacks network added +- `apps/bookstack/.env` — BOOKSTACK_OIDC_SECRET placeholder created +- `apps/openproject/docker-compose.yml` — OIDC env vars added, kitestacks network declared +- `apps/openproject/.env` — OPENPROJECT_OIDC_SECRET placeholder created + +Manual steps remaining (see `docs/authentik-sso-setup.md`): +- Create Authentik OAuth2/OIDC providers + applications for: Grafana, OpenWebUI, Kavita, BookStack, OpenProject +- Create Authentik Proxy Providers for: Shaarli, Uptime Kuma, LiteLLM +- Assign proxy providers to the Embedded Outpost +- Configure Forgejo OAuth2 source via Forgejo admin UI +- Update Cloudflare tunnel routes for proxy services +- Fill in client secrets in .env files and restart containers + +Reference: [Authentik SSO Setup Guide](authentik-sso-setup.md) + +--- + +## Cluster + +| Component | Status | +|-----------|--------| +| K3s | Active | +| FluxCD | Planned | +| Longhorn | Planned | + +## Applications + +| App | Path | SSO | +|-----|------|-----| +| Homepage | apps/homepage/ | Public (no auth) | +| Authentik | apps/authentik/ | Identity Provider | +| Grafana | apps/grafana/ | OAuth2 → Authentik | +| Open WebUI | apps/kite-ai/ | OIDC → Authentik | +| Forgejo | apps/forgejo/ | OAuth2 → Authentik | +| BookStack | apps/bookstack/ | OIDC → Authentik | +| OpenProject | apps/openproject/ | OIDC → Authentik | +| Kavita | apps/kavita/ | OIDC → Authentik | +| Shaarli | apps/shaarli/ | Proxy → Authentik | +| Uptime Kuma | apps/uptime-kuma/ | Proxy → Authentik | +| LiteLLM | apps/kite-ai/ | Proxy → Authentik | +| Portainer | apps/portainer/ | SSO excluded | +| Prometheus | apps/prometheus/ | SSO excluded | +| Linkding | apps/linkding/ | TBD | + +## SSO Documentation + +[Authentik SSO Setup Guide](authentik-sso-setup.md) — Full setup instructions, Authentik UI steps, Cloudflare tunnel changes, troubleshooting. diff --git a/docs/authentik-sso-setup.md b/docs/authentik-sso-setup.md new file mode 100644 index 0000000..5b16353 --- /dev/null +++ b/docs/authentik-sso-setup.md @@ -0,0 +1,287 @@ +# KiteStacks Authentik SSO Setup + +**Established:** 2026-06-08 +**Author:** kenpat +**Status:** In Progress — config files deployed, manual Authentik UI steps pending + +--- + +## Architecture + +All services sit behind Cloudflare Tunnels on the `kitestacks` Docker network. +`cloudflared` routes external traffic directly to each service container by hostname. +Authentik (`authentik:9000`) is the single identity provider. + +``` +Internet → Cloudflare → cloudflared → [service container] + ↕ + Authentik auth check +``` + +**Two integration patterns are used:** + +| Pattern | How it works | Services | +|---------|-------------|---------| +| Native OIDC/OAuth2 | App calls Authentik directly for login | Grafana, OpenWebUI, Forgejo, BookStack, OpenProject, Kavita | +| Authentik Proxy Provider | Cloudflare tunnel → Authentik (embedded outpost) → service | Shaarli, Uptime Kuma, LiteLLM | + +--- + +## SSO Status + +| Service | Subdomain | Port | Method | Status | +|---------|-----------|------|--------|--------| +| Authentik | auth.kitestacks.com | 9000 | (is the IdP) | ✅ Running | +| Grafana | grafana.kitestacks.com | 3000 | OAuth2 | ⚠️ env set, Authentik app needed | +| Kite AI (OpenWebUI) | ai.kitestacks.com | 8080 | OIDC | ⚠️ env set, Authentik app needed | +| Forgejo | gitforge.kitestacks.com | 3000 | OAuth2 | ⚠️ Forgejo admin UI config needed | +| BookStack | books.kitestacks.com* | 80 | OIDC | ⚠️ env set, Authentik app needed, CF tunnel needed | +| OpenProject | tasks.kitestacks.com | 80 | OIDC | ⚠️ env set, Authentik app needed | +| Kavita | kavita.kitestacks.com | 5000 | OIDC | ⚠️ appsettings.json updated, Authentik app needed | +| Shaarli | links.kitestacks.com | 80 | Proxy | ⚠️ Authentik Proxy Provider needed + CF tunnel update | +| Uptime Kuma | status.kitestacks.com | 3001 | Proxy | ⚠️ Authentik Proxy Provider needed + CF tunnel update | +| LiteLLM | llm.kitestacks.com | 4000 | Proxy | ⚠️ Authentik Proxy Provider needed + CF tunnel update | +| Portainer | portainer.kitestacks.com | 9000 | — | 🚫 SSO excluded | +| Prometheus | prometheus.kitestacks.com | 9090 | — | 🚫 SSO excluded | +| Node Exporter | node-exporter.kitestacks.com | 9100 | — | 🚫 SSO excluded | +| OpenRouter | openrouter.ai | — | — | 🚫 external, excluded | + +*BookStack subdomain placeholder — update `APP_URL` in `apps/bookstack/docker-compose.yml`. + +--- + +## Files Changed (2026-06-08) + +| File | What changed | +|------|-------------| +| `apps/authentik/docker-compose.yml` | Added `kitestacks` network declaration, `AUTHENTIK_ERROR_REPORTING__ENABLED: false` | +| `apps/kavita/config/appsettings.json` | `OpenIdConnectSettings.Enabled` → `true`, `Authority` set | +| `apps/bookstack/docker-compose.yml` | OIDC env vars added, `kitestacks` network added, `APP_URL` updated | +| `apps/bookstack/.env` | Created with `BOOKSTACK_OIDC_SECRET` placeholder | +| `apps/openproject/docker-compose.yml` | OIDC env vars added, `kitestacks` network declared | +| `apps/openproject/.env` | Created with `OPENPROJECT_OIDC_SECRET` placeholder | + +--- + +## Step 1 — Authentik Admin UI: Create Providers and Applications + +Go to **https://auth.kitestacks.com** → Admin Interface. + +### For each native OIDC service, create one OAuth2/OpenID Provider: + +**General settings (all providers):** +- Signing Key: select the default RS256 key +- Token validity: 10 minutes (access), 30 days (refresh) + +#### 1. Grafana + +- **Providers → Create → OAuth2/OpenID Provider** + - Name: `Grafana` + - Client type: `Confidential` + - Client ID: `grafana` + - Redirect URIs: `https://grafana.kitestacks.com/login/generic_oauth` + - Scopes: `openid`, `email`, `profile` +- **Applications → Create** + - Name: `Grafana`, Slug: `grafana` + - Provider: `Grafana` (above) +- Copy the **Client Secret** → put it in `/home/kenpat/docker/grafana/.env`: + ``` + GRAFANA_OAUTH_CLIENT_SECRET= + ``` +- Restart: `cd ~/docker/grafana && docker compose up -d` + +#### 2. Kite AI (Open WebUI) + +- **Providers → Create → OAuth2/OpenID Provider** + - Name: `Open WebUI`, Client ID: `open-webui` + - Redirect URIs: `https://ai.kitestacks.com/oauth/oidc/callback` + - Scopes: `openid`, `email`, `profile` +- **Applications → Create**: Name: `Kite AI`, Slug: `open-webui` +- Copy secret → `/home/kenpat/docker/kite-ai/.env`: + ``` + OPENWEBUI_OAUTH_CLIENT_SECRET= + ``` +- Restart: `cd ~/docker/kite-ai && docker compose up -d` + +#### 3. Kavita + +- **Providers → Create → OAuth2/OpenID Provider** + - Name: `Kavita`, Client ID: `kavita` + - Redirect URIs: `https://kavita.kitestacks.com/api/Account/OIDCCallback` + - Scopes: `openid`, `email`, `profile` +- **Applications → Create**: Name: `Kavita`, Slug: `kavita` +- Copy secret → `/home/kenpat/docker/kavita/config/appsettings.json`: + ```json + "Secret": "" + ``` +- Restart: `cd ~/docker/kavita && docker compose restart` (if a compose exists) or `docker restart kavita` + +#### 4. BookStack + +- **Providers → Create → OAuth2/OpenID Provider** + - Name: `BookStack`, Client ID: `bookstack` + - Redirect URIs: `https://books.kitestacks.com/oidc/callback` + *(adjust to your actual BookStack subdomain)* + - Scopes: `openid`, `email`, `profile` +- **Applications → Create**: Name: `BookStack`, Slug: `bookstack` +- Copy secret → `/home/kenpat/docker/bookstack/.env`: + ``` + BOOKSTACK_OIDC_SECRET= + ``` +- Set the real subdomain in `/home/kenpat/docker/bookstack/docker-compose.yml`: + - Update `APP_URL=https://.kitestacks.com` +- Restart: `cd ~/docker/bookstack && docker compose up -d` +- In Cloudflare dashboard: add tunnel route `.kitestacks.com` → `http://bookstack:80` + +#### 5. OpenProject + +- **Providers → Create → OAuth2/OpenID Provider** + - Name: `OpenProject`, Client ID: `openproject` + - Redirect URIs: `https://tasks.kitestacks.com/auth/oidc/callback` + - Scopes: `openid`, `email`, `profile` +- **Applications → Create**: Name: `OpenProject`, Slug: `openproject` +- Copy secret → `/home/kenpat/docker/openproject/.env`: + ``` + OPENPROJECT_OIDC_SECRET= + ``` +- Restart: `cd ~/docker/openproject && docker compose up -d` + - **Note:** Container is currently running `openproject/community:13` but compose + specifies `openproject/openproject:15`. Recreation will upgrade it. Verify data + migration after restart. The Cloudflare tunnel for `tasks.kitestacks.com` may need + updating from `openproject:8080` → `openproject:80` after the upgrade. + +--- + +### For proxy services, create Proxy Providers: + +These services have no native OIDC. Authentik will act as the reverse proxy. + +**After creating each Proxy Provider + Application, add all three to the Embedded Outpost:** +Outposts → `authentik Embedded Outpost` → Edit → move all three proxy applications to "Selected Applications". + +#### 6. Shaarli + +- **Providers → Create → Proxy Provider** + - Name: `Shaarli` + - Mode: `Reverse Proxy` + - External host: `https://links.kitestacks.com` + - Internal host: `http://shaarli:80` + - Internal host SSL validation: off +- **Applications → Create**: Name: `Shaarli`, Slug: `shaarli` +- **Cloudflare Tunnel**: Change `links.kitestacks.com` route from `http://shaarli:80` → `http://authentik:9000` + +#### 7. Uptime Kuma + +- **Providers → Create → Proxy Provider** + - Name: `Uptime Kuma` + - Mode: `Reverse Proxy` + - External host: `https://status.kitestacks.com` + - Internal host: `http://uptime-kuma:3001` +- **Applications → Create**: Name: `Uptime Kuma`, Slug: `uptime-kuma` +- **Cloudflare Tunnel**: Change `status.kitestacks.com` route from `http://uptime-kuma:3001` → `http://authentik:9000` + +#### 8. LiteLLM *(when ready to expose publicly)* + +- **Providers → Create → Proxy Provider** + - Name: `LiteLLM` + - Mode: `Reverse Proxy` + - External host: `https://llm.kitestacks.com` + - Internal host: `http://kite-litellm:4000` +- **Applications → Create**: Name: `LiteLLM`, Slug: `litellm` +- **Cloudflare Tunnel**: Add route `llm.kitestacks.com` → `http://authentik:9000` + +--- + +## Step 2 — Forgejo: Add Authentik OAuth2 Source + +Forgejo stores OAuth sources in its database (not in app.ini), so this requires the Forgejo admin UI. + +1. Go to **https://gitforge.kitestacks.com** → Site Administration → Authentication Sources +2. Click **Add Authentication Source** +3. Settings: + - Authentication Type: `OAuth2` + - Authentication Name: `authentik` + - OAuth2 Provider: `OpenID Connect` + - Client ID: `forgejo` + - Client Secret: *(create an Authentik app first — see below)* + - OpenID Connect Auto Discovery URL: + `https://auth.kitestacks.com/application/o/forgejo/.well-known/openid-configuration` + - Additional scopes: `email profile` +4. Save + +**Create the Authentik app for Forgejo first:** +- Provider: OAuth2/OpenID, Client ID: `forgejo` +- Redirect URI: `https://gitforge.kitestacks.com/user/oauth2/authentik/callback` +- Application slug: `forgejo` + +--- + +## Step 3 — Cloudflare Tunnel Updates + +In the Cloudflare Zero Trust Dashboard → Networks → Tunnels → your tunnel → Configure → Public Hostnames: + +| Hostname | Change From | Change To | +|----------|------------|-----------| +| `links.kitestacks.com` | `http://shaarli:80` | `http://authentik:9000` | +| `status.kitestacks.com` | `http://uptime-kuma:3001` | `http://authentik:9000` | +| `llm.kitestacks.com` | (new) | `http://authentik:9000` | +| `tasks.kitestacks.com` | `http://openproject:8080` | `http://openproject:80` *(after OpenProject upgrade)* | +| `.kitestacks.com` | (new) | `http://bookstack:80` | + +--- + +## Step 4 — Restart Containers After Config Changes + +After filling in all secrets in the `.env` files: + +```bash +cd ~/docker/grafana && docker compose up -d +cd ~/docker/kite-ai && docker compose up -d +cd ~/docker/bookstack && docker compose up -d +cd ~/docker/openproject && docker compose up -d +cd ~/docker/authentik && docker compose up -d +docker restart kavita +``` + +--- + +## Troubleshooting + +**OIDC redirect loop / 400 error** +- Check that the Redirect URI in the Authentik provider exactly matches what the app sends. +- Grafana: `https://grafana.kitestacks.com/login/generic_oauth` (no trailing slash) + +**Kavita "OIDC is not configured" message** +- The `appsettings.json` change requires a container restart: `docker restart kavita` +- Verify `Enabled: true` and `Secret` is not empty. + +**BookStack redirects to `http://192.168.1.205:6875`** +- `APP_URL` must be updated to the real HTTPS domain and the container recreated. + +**OpenProject: OIDC provider not visible in login** +- Env var format is version-specific. If env vars don't work in v15, configure via: + Administration → Authentication → OpenID Connect Providers → Add + +**Proxy services (Shaarli/Uptime Kuma) show Authentik login but then 502** +- Verify the Embedded Outpost has the proxy providers assigned. +- Verify internal host is reachable: `docker exec authentik curl -v http://shaarli:80` + +--- + +## Service-to-Container Name Reference + +| Subdomain | Container Name | Internal Port | +|-----------|---------------|--------------| +| auth.kitestacks.com | authentik | 9000 | +| grafana.kitestacks.com | grafana | 3000 | +| ai.kitestacks.com | kite-openwebui | 8080 | +| gitforge.kitestacks.com | forgejo | 3000 | +| tasks.kitestacks.com | openproject | 80 (after upgrade) | +| kavita.kitestacks.com | kavita | 5000 | +| links.kitestacks.com | shaarli | 80 | +| status.kitestacks.com | uptime-kuma | 3001 | +| llm.kitestacks.com | kite-litellm | 4000 | +| www.kitestacks.com | homepage | 3000 | +| portainer.kitestacks.com | portainer | 9000 (excluded) | +| prometheus.kitestacks.com | prometheus | 9090 (excluded) | +| node-exporter.kitestacks.com | node-exporter | 9100 (excluded) |