keywarden/OIDC_SOCIAL_SETUP.md

# 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.