docs: add complete SSO configuration reference

2026-05-21 02:18:50 +09:00
parent 4286bdb237
commit f6d193dc4f
1 changed files with 128 additions and 0 deletions
--- a/docs/sso.md
+++ b/docs/sso.md
@@ -0,0 +1,128 @@
+# SSO 연동 현황 (Authentik)
+
+> Authentik: `https://auth.du5t.xyz` | 버전: 2025.12
+> Embedded Outpost PK: `999d7409-0ec6-4e81-ab37-cb4cd4b1557c`
+
+## Provider 목록
+
+| PK | Provider명 | 타입 | 연결 Application |
+|---|---|---|---|
+| 2 | `grafana-oidc` | OAuth2/OIDC | Grafana |
+| 3 | `gitea-oidc` | OAuth2/OIDC | Gitea |
+| 4 | `nextcloud-oidc` | OAuth2/OIDC | Nextcloud |
+| 5 | `open-webui-oidc` | OAuth2/OIDC | Open WebUI |
+| 6 | `prometheus-proxy` | Proxy | Prometheus |
+| 7 | `filebrowser-proxy` | Proxy | FileBrowser |
+| 8 | `comfyui-proxy` | Proxy | ComfyUI |
+
+## OIDC 연동 상세
+
+### Grafana (`grafana.ini`)
+
+```ini
+[auth.generic_oauth]
+enabled = true
+name = authentik
+client_id = gO2Rk6LOyDU9CZc7DdXqNlEwfK8lTZmGb2nnBJOk
+scopes = openid profile email
+auth_url = https://auth.du5t.xyz/application/o/authorize/
+token_url = https://auth.du5t.xyz/application/o/token/
+api_url = https://auth.du5t.xyz/application/o/userinfo/
+role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || 'Viewer'
+signout_redirect_url = https://auth.du5t.xyz/application/o/grafana/end-session/
+use_pkce = true
+```
+
+### Gitea
+
+```bash
+podman exec --user git gitea gitea admin auth add-oauth \
+  --name "authentik" \
+  --provider "openidConnect" \
+  --key "<CLIENT_ID>" \
+  --secret "<CLIENT_SECRET>" \
+  --auto-discover-url "https://auth.du5t.xyz/application/o/gitea/.well-known/openid-configuration"
+```
+
+### Nextcloud
+
+```bash
+podman exec --user www-data nextcloud-app php occ app:install user_oidc
+podman exec --user www-data nextcloud-app php occ user_oidc:provider authentik \
+  --clientid="<CLIENT_ID>" \
+  --clientsecret="<CLIENT_SECRET>" \
+  --discoveryuri="https://auth.du5t.xyz/application/o/nextcloud/.well-known/openid-configuration" \
+  --unique-uid=1
+```
+
+### Open WebUI (환경변수)
+
+```ini
+Environment=ENABLE_OAUTH_SIGNUP=true
+Environment=OAUTH_PROVIDER_NAME=authentik
+Environment=OPENID_PROVIDER_URL=https://auth.du5t.xyz/application/o/open-webui/.well-known/openid-configuration
+Environment=OAUTH_CLIENT_ID=<CLIENT_ID>
+Environment=OAUTH_CLIENT_SECRET=<CLIENT_SECRET>
+Environment=OAUTH_SCOPES=openid email profile
+```
+
+## Proxy Provider 연동 상세
+
+NPM의 백엔드를 `10.89.0.20:9000` (Authentik Embedded Outpost)으로 설정한다.
+Outpost가 `Host` 헤더를 보고 어느 Proxy Provider를 적용할지 결정한다.
+
+```
+NPM (443) ─→ Authentik Outpost (10.89.0.20:9000)
+                    │
+                    ├─ Host: prometheus.du5t.xyz  → 10.89.0.30:9090
+                    ├─ Host: file.du5t.xyz        → 10.89.0.5:8080
+                    └─ Host: comfy.du5t.xyz       → 10.89.0.1:8188
+```
+
+인증되지 않은 요청:
+```
+302 → https://<domain>/outpost.goauthentik.io/start?rd=<original_url>
+    → https://auth.du5t.xyz/flows/default-authentication-flow/
+```
+
+## API 토큰 재발급
+
+Authentik API 토큰은 만료 시 재발급이 필요하다.
+
+```bash
+podman exec authentik-worker python -m manage shell -c "
+from authentik.core.models import Token, TokenIntents, User
+user = User.objects.get(username='akadmin')
+t = Token.objects.filter(identifier='cli-admin-token').first()
+if t: t.delete()
+token = Token.objects.create(
+    identifier='cli-admin-token', user=user, intent=TokenIntents.INTENT_API
+)
+print(token.key)
+"
+```
+
+## 신규 서비스 Authentik 연동 절차
+
+### OIDC 방식
+
+1. Authentik API: `POST /api/v3/providers/oauth2/` — Provider 생성
+2. Authentik API: `POST /api/v3/core/applications/` — Application 생성
+3. 서비스 측 OIDC 설정 (Discovery URL 패턴: `https://auth.du5t.xyz/application/o/<slug>/.well-known/openid-configuration`)
+
+### Proxy Provider 방식
+
+1. Authentik API: `POST /api/v3/providers/proxy/` — Provider 생성 (`external_host`, `internal_host` 지정)
+2. Authentik API: `POST /api/v3/core/applications/` — Application 생성
+3. Authentik API: `PATCH /api/v3/outposts/instances/999d7409-.../` — Outpost providers 배열에 추가
+4. NPM DB: `UPDATE proxy_host SET forward_host='10.89.0.20', forward_port=9000 WHERE domain_names='...'`
+5. NPM nginx conf 파일 직접 수정 후 `podman exec npm-app nginx -s reload`
+
+## 미적용 서비스 (향후 계획)
+
+| 서비스 | 권장 방식 | 비고 |
+|---|---|---|
+| JupyterHub | OIDC (`oauthenticator.GenericOAuthenticator`) | `jupyterhub_config.py` 수정 필요 |
+| SFTPGo | OIDC (Web Admin > Settings > OIDC) | 웹 UI에서 설정 가능 |
+| Jellyfin | OIDC (SSO Plugin) | 플러그인 설치 필요 |
+| Ollama API | Proxy Provider | 현재 무인증 노출 상태 |