🔐 Authentication Overview
Booklore 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
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
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.
Booklore's OIDC support includes:
- Server-side token exchange with PKCE
- Automatic user provisioning on first login
- Group mapping to sync provider groups to Booklore 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
Step-by-step walkthroughs with screenshots:
Full Settings Reference
See OIDC Settings for every configuration option, claim mappings, group mapping, and example configurations.
🤔 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
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, Booklore stops auto-redirecting after 3 attempts and shows a link to local login.
❓ 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 Booklore 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 Booklore permissions and library access.