feat(idp): add keycloak-first support with authentik fallback

README.md

@@ -21,7 +21,26 @@ cp .env.example .env
 python scripts/generate_api_key_hash.py 'YOUR_PLAIN_KEY'
 ```
 
-## Authentik JWT setup
+## IdP JWT setup（Keycloak 優先）
+
+- 若設定 `KEYCLOAK_BASE_URL` + `KEYCLOAK_REALM`，後端會優先走 Keycloak。
+- 未設定 Keycloak 時，才走 `AUTHENTIK_*`。
+
+### Keycloak
+- 必填：
+  - `KEYCLOAK_BASE_URL`
+  - `KEYCLOAK_REALM`
+  - `KEYCLOAK_CLIENT_ID`
+  - `KEYCLOAK_CLIENT_SECRET`
+- 可選：
+  - `KEYCLOAK_ISSUER`（預設：`<base>/realms/<realm>`）
+  - `KEYCLOAK_JWKS_URL`（預設：`<issuer>/protocol/openid-connect/certs`）
+  - `KEYCLOAK_TOKEN_ENDPOINT`（預設：`<issuer>/protocol/openid-connect/token`）
+  - `KEYCLOAK_USERINFO_ENDPOINT`（預設：`<issuer>/protocol/openid-connect/userinfo`）
+  - `KEYCLOAK_AUDIENCE`
+  - `KEYCLOAK_VERIFY_TLS`（預設 true）
+
+### Authentik（備援）
 
 - Configure at least one of:
   - `AUTHENTIK_JWKS_URL`
@@ -33,9 +52,16 @@ python scripts/generate_api_key_hash.py 'YOUR_PLAIN_KEY'
   - `AUTHENTIK_TOKEN_ENDPOINT` (default: `<AUTHENTIK_BASE_URL>/application/o/token/`)
   - `AUTHENTIK_USERINFO_ENDPOINT` (optional, default inferred from issuer/base URL; used to fill missing email/name claims)
 
-## Authentik Admin API setup
+## IdP Admin API setup
 
-- Required for `/internal/authentik/users/ensure`:
+- Keycloak（優先）
+  - `KEYCLOAK_BASE_URL`
+  - `KEYCLOAK_REALM`
+  - `KEYCLOAK_ADMIN_CLIENT_ID`
+  - `KEYCLOAK_ADMIN_CLIENT_SECRET`
+  - `KEYCLOAK_ADMIN_REALM`（可選，預設同 `KEYCLOAK_REALM`）
+
+- Authentik（備援）
   - `AUTHENTIK_BASE_URL`
   - `AUTHENTIK_ADMIN_TOKEN`
   - `AUTHENTIK_VERIFY_TLS`
@@ -49,7 +75,7 @@ python scripts/generate_api_key_hash.py 'YOUR_PLAIN_KEY'
 - `GET /me/permissions/snapshot` (Bearer token required)
 - `POST /internal/users/upsert-by-sub`
 - `GET /internal/permissions/{user_sub}/snapshot`
-- `POST /internal/authentik/users/ensure`
+- `POST /internal/idp/users/ensure`（相容：`/internal/authentik/users/ensure`）
 - `POST /admin/permissions/grant`
 - `POST /admin/permissions/revoke`
 - `GET|POST /admin/systems`