Single sign-on (OIDC)

Tome can authenticate against an external OpenID Connect identity provider, so you and your users sign in with the same identity (and passkeys, if your IdP supports them) you use everywhere else. It works with any compliant OIDC provider — Pocket ID, Authelia, Authentik, Keycloak, Zitadel, Google, and more. The examples below use Pocket ID, but the Tome side is standard OIDC.

How it works

Tome acts as an OIDC relying party. When a user clicks Sign in with SSO, Tome redirects to your IdP; after they authenticate, the IdP redirects back and Tome mints its normal session token. Because the callback issues the same token as a password login, everything downstream — the API, OPDS, the KOReader plugin, API tokens — is unchanged.

The IdP's groups claim maps to a Tome role (admin / member / guest), so you manage access from your identity provider.

1. Register Tome at your IdP

In your provider, create an OIDC client/application for Tome:

1. Create a new OIDC client named e.g. Tome.
2. Set the callback / redirect URL to https://tome.example.com/api/auth/oidc/callback (your public Tome URL + that path).
3. Keep it a confidential client (it has a secret) and enable PKCE.
4. Optional — set a client logo: paste https://tome.bndct.sh/tome-icon.png, or download it and host it yourself (recommended if you'd rather not depend on this site staying up).
5. Copy the Client ID and Client Secret.
6. Create groups for your roles — e.g. tome_admins and tome_members — and add your users. If your IdP gates access per-client (Pocket ID's "Allowed User Groups"), include those groups so the groups claim is emitted.

2. Configure Tome

Set these environment variables on your Tome container and restart:

TOME_OIDC_ENABLED=true
TOME_OIDC_ISSUER=https://auth.example.com
TOME_OIDC_CLIENT_ID=<from your IdP>
TOME_OIDC_CLIENT_SECRET=<from your IdP>
TOME_OIDC_ADMIN_GROUP=tome_admins
TOME_OIDC_MEMBER_GROUP=tome_members
TOME_OIDC_DEFAULT_ROLE=guest
# Behind a reverse proxy, pin your public origin so the redirect is correct:
TOME_PUBLIC_URL=https://tome.example.com

With SSO enabled, a Sign in with SSO button appears on the login page. Done.

Group → role mapping

On each login Tome reads the groups claim and resolves a role, admin first:

Adding SSO to an existing account

Already have a Tome account with your library, reading progress, and shelves? Link SSO to it instead of creating a second account:

1. Sign in to your existing account with your password (not SSO).
2. Go to Settings → Single Sign-On → Link SSO and authenticate at your IdP.
3. From then on, Sign in with SSO lands you in that same account. Your password keeps working too.

Behind a reverse proxy

If Tome runs behind a TLS-terminating reverse proxy (Caddy, Traefik, Pangolin, nginx, …), the app server sees plain http internally. Left unhandled, Tome would hand your IdP an http:// redirect URL that won't match the https:// one you registered, and the login would fail.

Pick one:

• Set TOME_PUBLIC_URL=https://tome.example.com (recommended — it also pins the KOReader plugin URL), or
• Set TOME_OIDC_REDIRECT_URL=https://tome.example.com/api/auth/oidc/callback explicitly, or
• Ensure your proxy forwards X-Forwarded-Proto: https (Tome honors it).

Logout

Logging out of Tome clears your Tome session only — it does not end your IdP session. If your IdP still has an active session, the next Sign in with SSO may sign you straight back in without a fresh prompt. To fully sign out, also log out at your identity provider.

Troubleshooting