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 (GitHub)

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

pip install -r requirements.txt
cd app
python manage.py migrate

2. Core auth mode

# 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):

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):

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:

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:

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:

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:

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. GitHub social provider

Enable GitHub by credentials (or explicit *_ENABLED=true).

KEYWARDEN_SITE_ID=1
KEYWARDEN_SOCIAL_REQUIRE_VERIFIED_EMAIL=true

KEYWARDEN_SOCIAL_GITHUB_ENABLED=true
KEYWARDEN_SOCIAL_GITHUB_CLIENT_ID=<github-client-id>
KEYWARDEN_SOCIAL_GITHUB_CLIENT_SECRET=<github-secret>

Keywarden includes social auth URLs under:

/accounts/sso/

Provider callback URL to register:

• GitHub: https://<your-keywarden-domain>/accounts/sso/github/login/callback/

Security behavior:

• Social auto-onboarding is disabled.
• Users must already exist in Keywarden and must link GitHub from /accounts/profile/.
• After linking, Login with GitHub is available as an additional login method.
• Local Keywarden email and GitHub email may differ; matching is by linked GitHub subject (uid).
• Native password reset/email verification are disabled for SSO-linked accounts and handled in the IdP.

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:

KEYWARDEN_OIDC_SYNC_ADMIN_FROM_GROUPS=true
KEYWARDEN_OIDC_ADMIN_GROUPS=keywarden-admins,platform-admins
KEYWARDEN_OIDC_GROUPS_CLAIM=groups

Demotion behavior (optional):

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 GitHub login only succeeds for previously linked users.
• Repeat logins map to same local user via external identity subject.
• Changing provider email for the same subject causes login rejection.