Adding Multi-User Support and OIDC to Shelfmark

I’ve been using Shelfmark to manage book downloads on my homelab. It’s basically Sonarr/Radarr but for books. You search, it downloads, everyone’s happy. Works great for one person.

The problem is I wanted to share it with a few other people in my household, and Shelfmark had no concept of users. Everyone shares the same session, same settings, same download queue. No way to give someone their own BookLore library or download folder. And if you’re already running Pocket ID or Authentik for SSO, tough luck because there was no OIDC support either.

So I built it. PR #606 adds OIDC authentication and full multi-user support.

Users are a thing now

Shelfmark now has a proper user database. Admins get a new Users tab in settings where they can create accounts, assign roles, and set per-user download settings.

Each user can have their own download destination (different folder paths), their own BookLore library and path (selected from a dropdown, not typed by hand), and their own email recipients. There’s also a {User} template variable you can use in destination paths, so set it to /books/{User}/ and each person’s downloads automatically go to their own subfolder.

Non-admin users only see their own downloads. The sidebar, the queue status, the real-time WebSocket progress updates are all filtered per user. Admins still see everything.

OIDC login

If you’re running an OIDC provider (Pocket ID, Authentik, Authelia, Keycloak, whatever), Shelfmark can now use it. Set AUTH_METHOD to oidc in the Security settings, point it at your discovery URL, and you’re done. Users get a “Sign in with OIDC” button on the login page.

Some things I added to make the OIDC experience not painful:

• New users who log in via OIDC automatically get an account (you can turn this off if you want to pre-create users manually)
• You can map an OIDC group to admin role, so anyone in that group becomes an admin
• Even with OIDC enabled, admins can still log in with a password, which prevents the classic “I misconfigured OIDC and now I’m locked out” scenario
• You can’t even enable OIDC without having at least one local admin account. The settings UI blocks you from saving if you’d lock yourself out
• If you pre-create a user with an email address and someone logs in via OIDC with that same email, the accounts link automatically

How to set it up

For just multi-user with passwords: go to Settings > Security, set auth to Built-in, then go to Settings > Users and create your users. That’s it.

For OIDC: first create at least one local admin under Settings > Users. Then go to Settings > Security, set auth to OIDC, fill in your discovery URL, client ID, and client secret from your OIDC provider. Optionally set an admin group. Save, and the login page now shows an OIDC button.

Per-user download settings are on the Users tab. Click a user to set their overrides. Anything left empty falls back to the global defaults.

Migration

No migration scripts. No database changes. The user database (users.db) gets created automatically on first startup. If you’re upgrading from the old single-user builtin auth, your credentials auto-migrate the first time you log in.

Existing setups with no auth, CWA, or proxy auth are completely unaffected. Nothing changes unless you switch to builtin or OIDC mode.

What’s next

BookLore OIDC integration is on the roadmap, using your OIDC token to authenticate with BookLore directly instead of separate credentials. But that’s a future PR.

If you’re running Shelfmark and want multi-user support, the PR is up at calibrain/shelfmark#606. Feel free to try it out and leave feedback.