Authentication Overview
Grimmory supports two authentication methods: local (built-in username/password) and OIDC (single sign-on with an external identity provider). You can use either one or both at the same time.
Local Authentication
Section titled “Local Authentication”Built-in username and password login. Works immediately after installation with zero external dependencies. You create users in Settings > Users and they log in with a password. Simple as that.
Local auth is always available as a fallback, even when OIDC is enabled. Admins can reach the local login form at /login?local=true regardless of any OIDC settings.
OIDC Authentication
Section titled “OIDC Authentication”Sign in with an external identity provider like Authentik, Keycloak, Authelia, or Pocket ID. Users click one button and authenticate with the same account they use for your other self-hosted apps.
Grimmory’s OIDC support includes:
- Server-side token exchange with PKCE
- Automatic user provisioning on first login
- Group mapping to sync provider groups to Grimmory permissions and library access
- Back-channel logout to keep sessions in sync across apps
- OIDC-Only Mode to hide local login and redirect everyone to your provider
- Account linking to migrate existing users without losing their data
Provider Setup Guides
Section titled “Provider Setup Guides”Step-by-step walkthroughs with screenshots:
Full Settings Reference
Section titled “Full Settings Reference”See OIDC Settings for every configuration option, claim mappings, group mapping, and example configurations.
Which Should I Use?
Section titled “Which Should I Use?”| Setup | When to use it |
|---|---|
| Local only | Solo use or a small group. No identity provider needed. |
| OIDC | You already run an identity provider and want SSO, MFA, and centralized access control. |
| Both | During migration from local to OIDC. Users can use either method. |
| OIDC-Only | You want to enforce SSO for everyone. Local login is hidden (admin backdoor still works). |
Safety Nets
Section titled “Safety Nets”Admin backdoor: /login?local=true always shows the local login form, even in OIDC-Only Mode.
Kill switch: Set FORCE_DISABLE_OIDC=true as an environment variable and restart to disable OIDC entirely, regardless of database settings.
Loop protection: If OIDC-Only Mode is on and your provider keeps failing, Grimmory stops auto-redirecting after 3 attempts and shows a link to local login.
Common Questions
Section titled “Common Questions”What if my identity provider goes down?
Local login still works. Use /login?local=true.
Do I need to migrate existing users when enabling OIDC? No. Enable “Link Existing Local Accounts” and users are linked to their OIDC identity on first SSO login, keeping all their data.
Are usernames case-sensitive? Yes. The OIDC username must exactly match the Grimmory username.
Does OIDC support MFA? Yes. Whatever your provider supports works automatically.
Can different users have different permissions? Yes. Use Group Mapping to map provider groups to Grimmory permissions and library access.