OIDC Integration: Supports Authentik officially, other solutions currently untested. Social login not implemented

OIDC_SOCIAL_SETUP.md

@@ -0,0 +1,185 @@
+# Keywarden OIDC and Social Login Setup
+
+This guide configures:
+- OIDC client login (Authentik, Authelia, Keycloak, or other OIDC IdP)
+- Social login (Google, GitHub, Apple)
+
+Security model implemented by Keywarden:
+- External identities are mapped by immutable provider subject (`sub`/`uid`) and provider ID.
+- User email is immutable after account creation.
+- Login is denied if a provider later returns a different email for an already-linked identity.
+- Optional group-to-admin mapping is available for OIDC.
+
+## 1. Install and migrate
+
+```bash
+pip install -r requirements.txt
+cd app
+python manage.py migrate
+```
+
+## 2. Core auth mode
+
+```env
+# native | hybrid | oidc
+KEYWARDEN_AUTH_MODE=hybrid
+```
+
+- `native`: username/password only
+- `hybrid`: username/password + OIDC/social (recommended)
+- `oidc`: force OIDC login only
+
+## 3. OIDC client configuration (generic)
+
+Use discovery endpoint (recommended):
+
+```env
+KEYWARDEN_OIDC_CLIENT_ID=keywarden
+KEYWARDEN_OIDC_CLIENT_SECRET=replace-with-secret
+KEYWARDEN_OIDC_DISCOVERY_ENDPOINT=https://idp.example.com/application/o/keywarden/.well-known/openid-configuration
+KEYWARDEN_OIDC_ISSUER=https://idp.example.com/application/o/keywarden/
+KEYWARDEN_OIDC_SCOPES=openid email profile groups
+KEYWARDEN_OIDC_PROVIDER_ID=corporate-sso
+KEYWARDEN_OIDC_REQUIRE_VERIFIED_EMAIL=true
+KEYWARDEN_OIDC_EMAIL_CLAIM=email
+KEYWARDEN_OIDC_EMAIL_VERIFIED_CLAIM=email_verified
+KEYWARDEN_OIDC_USERNAME_CLAIM=preferred_username
+KEYWARDEN_OIDC_GROUPS_CLAIM=groups
+
+# Optional admin sync from IdP groups
+KEYWARDEN_OIDC_SYNC_ADMIN_FROM_GROUPS=false
+KEYWARDEN_OIDC_ADMIN_GROUPS=keywarden-admins,admins
+KEYWARDEN_OIDC_ADMIN_DEMOTE_ON_MISS=false
+```
+
+Manual endpoint mode (if discovery is unavailable):
+
+```env
+KEYWARDEN_OIDC_CLIENT_ID=keywarden
+KEYWARDEN_OIDC_CLIENT_SECRET=replace-with-secret
+KEYWARDEN_OIDC_AUTHORIZATION_ENDPOINT=https://idp.example.com/oauth2/authorize
+KEYWARDEN_OIDC_TOKEN_ENDPOINT=https://idp.example.com/oauth2/token
+KEYWARDEN_OIDC_USER_ENDPOINT=https://idp.example.com/oauth2/userinfo
+KEYWARDEN_OIDC_JWKS_ENDPOINT=https://idp.example.com/oauth2/jwks
+```
+
+Redirect URI to register in your IdP:
+
+```text
+https://<your-keywarden-domain>/oidc/callback/
+```
+
+## 4. IdP examples
+
+## Authentik
+
+- Create an OAuth2/OpenID Provider in Authentik.
+- Client type: Confidential.
+- Redirect URI: `https://<your-keywarden-domain>/oidc/callback/`
+- Scopes: `openid email profile` (plus `groups` if using group mapping).
+
+Example:
+
+```env
+KEYWARDEN_OIDC_CLIENT_ID=keywarden
+KEYWARDEN_OIDC_CLIENT_SECRET=<authentik-secret>
+KEYWARDEN_OIDC_DISCOVERY_ENDPOINT=https://auth.example.com/application/o/keywarden/.well-known/openid-configuration
+KEYWARDEN_OIDC_ISSUER=https://auth.example.com/application/o/keywarden/
+KEYWARDEN_OIDC_GROUPS_CLAIM=groups
+```
+
+## Authelia
+
+- Configure an OIDC client in Authelia.
+- Set redirect URI to `https://<your-keywarden-domain>/oidc/callback/`.
+- Ensure `email` and `profile` claims are emitted.
+
+Example:
+
+```env
+KEYWARDEN_OIDC_CLIENT_ID=keywarden
+KEYWARDEN_OIDC_CLIENT_SECRET=<authelia-secret>
+KEYWARDEN_OIDC_DISCOVERY_ENDPOINT=https://auth.example.com/.well-known/openid-configuration
+KEYWARDEN_OIDC_ISSUER=https://auth.example.com
+KEYWARDEN_OIDC_EMAIL_CLAIM=email
+```
+
+## Keycloak
+
+- Create a Confidential client in a realm.
+- Valid redirect URI: `https://<your-keywarden-domain>/oidc/callback/`
+- Standard flow enabled.
+
+Example:
+
+```env
+KEYWARDEN_OIDC_CLIENT_ID=keywarden
+KEYWARDEN_OIDC_CLIENT_SECRET=<keycloak-secret>
+KEYWARDEN_OIDC_DISCOVERY_ENDPOINT=https://id.example.com/realms/main/.well-known/openid-configuration
+KEYWARDEN_OIDC_ISSUER=https://id.example.com/realms/main
+KEYWARDEN_OIDC_GROUPS_CLAIM=groups
+```
+
+## 5. Social providers
+
+Enable providers by credentials (or explicit `*_ENABLED=true`).
+
+```env
+KEYWARDEN_SITE_ID=1
+KEYWARDEN_SOCIAL_REQUIRE_VERIFIED_EMAIL=true
+
+KEYWARDEN_SOCIAL_GOOGLE_ENABLED=true
+KEYWARDEN_SOCIAL_GOOGLE_CLIENT_ID=<google-client-id>
+KEYWARDEN_SOCIAL_GOOGLE_CLIENT_SECRET=<google-secret>
+
+KEYWARDEN_SOCIAL_GITHUB_ENABLED=true
+KEYWARDEN_SOCIAL_GITHUB_CLIENT_ID=<github-client-id>
+KEYWARDEN_SOCIAL_GITHUB_CLIENT_SECRET=<github-secret>
+
+KEYWARDEN_SOCIAL_APPLE_ENABLED=true
+KEYWARDEN_SOCIAL_APPLE_CLIENT_ID=<apple-services-id>
+KEYWARDEN_SOCIAL_APPLE_CLIENT_SECRET=<apple-client-secret-jwt>
+```
+
+Keywarden includes social auth URLs under:
+
+```text
+/accounts/sso/
+```
+
+Provider callback URLs to register:
+- Google: `https://<your-keywarden-domain>/accounts/sso/google/login/callback/`
+- GitHub: `https://<your-keywarden-domain>/accounts/sso/github/login/callback/`
+- Apple: `https://<your-keywarden-domain>/accounts/sso/apple/login/callback/`
+
+## 6. Email immutability behavior
+
+- Once a Keywarden user is created, email cannot be edited via API/admin/social/OIDC updates.
+- If an IdP/social provider later reports a different email for the same external identity, login is blocked.
+- This prevents account takeover via claim/email drift.
+
+## 7. Optional OIDC admin mapping
+
+To map IdP groups to Keywarden administrator:
+
+```env
+KEYWARDEN_OIDC_SYNC_ADMIN_FROM_GROUPS=true
+KEYWARDEN_OIDC_ADMIN_GROUPS=keywarden-admins,platform-admins
+KEYWARDEN_OIDC_GROUPS_CLAIM=groups
+```
+
+Demotion behavior (optional):
+
+```env
+KEYWARDEN_OIDC_ADMIN_DEMOTE_ON_MISS=true
+```
+
+When enabled, a previously promoted user is demoted to standard user if admin groups are no longer present.
+
+## 8. Validation checklist
+
+- Login page shows social buttons for enabled providers.
+- `/oidc/authenticate/` starts IdP login.
+- First login auto-creates local user.
+- Repeat logins map to same local user via external identity subject.
+- Changing provider email for the same subject causes login rejection.