From 9906b716b1a42068ea26582784c83f8367c99cc1 Mon Sep 17 00:00:00 2001
From: gm <weimdo_@naver.com>
Date: Tue, 26 May 2026 16:20:30 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Authentik=20oauth2=20=EC=97=B0=EB=8F=99?=
 =?UTF-8?q?=20=EC=83=81=EC=84=B8=20=EB=B0=8F=20=EC=9A=B4=EC=98=81=20?=
 =?UTF-8?q?=EC=A3=BC=EC=9D=98=EC=82=AC=ED=95=AD=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 84 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6dd3053..6e97a50 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
 | 도메인 | `wiki.du5t.xyz` |
 | DB | `postgres-main` — `wikijs` 데이터베이스 |
 | 데이터 | `/podman/data/wikijs/data` |
-| 인증 | Authentik OIDC (관리자 패널에서 설정) |
+| 인증 | Authentik OAuth2 (strategy: `oauth2`, Provider PK=9) |
 
 ## 파일 구성
 
@@ -23,13 +23,91 @@ wikijs.env.example        ← 환경변수 템플릿
 
 실제 환경변수 파일은 `/podman/env/wikijs.env` (서버 로컬, 미추적).
 
+## Authentik 연동 상세
+
+### Provider 정보
+
+| 항목 | 값 |
+|---|---|
+| Provider PK | `9` |
+| Provider명 | `wikijs-provider` |
+| Strategy | `oauth2` (passport-oauth2, Generic OAuth2) |
+| Strategy UUID | `a2d864cd-dfc4-4a75-a891-d768fd8d173a` |
+| Callback URL | `https://wiki.du5t.xyz/login/a2d864cd-dfc4-4a75-a891-d768fd8d173a/callback` |
+| Authorization Flow | implicit-consent |
+
+> **`oidc` 대신 `oauth2` 전략을 사용하는 이유**  
+> Wiki.js에 포함된 `passport-openidconnect` v0.1.2가 Authentik의 토큰 응답을 처리하는 과정에서  
+> `invalid_grant` 오류를 반환한다. `passport-oauth2`는 JWT ID 토큰 검증 없이 userinfo 엔드포인트만  
+> 사용하므로 이 문제를 우회한다.
+
+### Authentik Property Mappings (필수)
+
+Provider PK=9에 아래 3개 매핑이 없으면 userinfo 엔드포인트가 `Scope mismatch` 오류를 반환한다.
+
+| Mapping | Scope |
+|---|---|
+| `authentik default OAuth Mapping: OpenID 'openid'` | openid |
+| `authentik default OAuth Mapping: OpenID 'profile'` | profile |
+| `authentik default OAuth Mapping: OpenID 'email'` | email |
+
+```bash
+AUTHENTIK_TOKEN="<token>"
+curl -s -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
+  "https://auth.du5t.xyz/api/v3/providers/oauth2/9/" | python3 -c \
+  "import sys,json; print(json.load(sys.stdin)['property_mappings'])"
+```
+
+### Wiki.js 전략 등록 (GraphQL)
+
+config 값은 반드시 `{"v": <value>}` 형태로 JSON 인코딩해야 한다.
+
+```bash
+WIKI_TOKEN=$(curl -s -X POST https://wiki.du5t.xyz/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query":"mutation{authentication{login(username:\"<email>\",password:\"<pass>\",strategy:\"local\"){jwt}}}"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['authentication']['login']['jwt'])")
+```
+
+전략 등록 시 주요 config 항목:
+
+| key | value |
+|---|---|
+| `authorizationURL` | `https://auth.du5t.xyz/application/o/authorize/` |
+| `tokenURL` | `https://auth.du5t.xyz/application/o/token/` |
+| `userInfoURL` | `https://auth.du5t.xyz/application/o/userinfo/` |
+| `userIdClaim` | `sub` |
+| `displayNameClaim` | `name` |
+| `emailClaim` | `email` |
+| `scope` | `openid profile email` |
+| `enableCSRFProtection` | `false` |
+
+## 그룹 및 권한 구조
+
+| 그룹 ID | 이름 | autoEnrollGroups | 비고 |
+|---|---|---|---|
+| 1 | Administrators | — | `manage:system` 권한, 관리자 페이지 접근 |
+| 2 | Guests | — | 읽기 전용 |
+| 3 | Users | ✓ (SSO 신규 유저 자동 배정) | 읽기/쓰기 |
+
+> **pageRules `path` 주의사항**  
+> 그룹 pageRules의 `path` 값은 `""` (빈 문자열)이어야 한다.  
+> `"/"` 로 설정 시 checkAccess 내부에서 `"/" + path = "//"` 가 되어 모든 경로 매칭이 실패한다.
+
+관리자 계정은 별도로 Administrators 그룹에 추가:
+
+```sql
+-- Wiki.js PostgreSQL (postgres-main, wikijs DB)
+INSERT INTO "userGroups" ("userId", "groupId") VALUES (<userId>, 1);
+```
+
 ## 초기 설정 순서
 
-1. `systemctl start wikijs` 후 `wiki.du5t.xyz` 접속
-2. 관리자 이메일 / 비밀번호 설정 (Setup Wizard)
-3. 관리자 패널 → Authentication → Add → Generic OpenID Connect
-   - Authentik에서 OAuth2 Provider + Application 생성 후 Client ID/Secret 입력
-   - Callback URL: `https://wiki.du5t.xyz/login/4d0871b7-3a3b-49a4-bef2-b34618d5dbbd/callback`
+1. `systemctl start wikijs`
+2. Setup Wizard 완료 (`POST /finalize` — 관리자 이메일/비밀번호 설정)
+3. Authentik: Provider(PK=9) + Application 생성, property_mappings 3개 설정
+4. Wiki.js GraphQL: `updateStrategies` mutation으로 `oauth2` 전략 등록
+5. 관리자 계정을 Administrators 그룹(id=1)에 추가
 
 ## 운영