Single sign-on (OpenID Connect)
Single sign-on is optional and works alongside local passwords. Tested against Authelia, Keycloak, Authentik, and Entra ID; anything with OpenID Connect discovery and the authorization code flow should work.
Register Maki with your provider as a confidential or public client using the authorization code
flow with PKCE. The redirect URI is https://<your-host>/api/v1/auth/oidc/callback. Then fill in
Settings → Users & security → Single sign-on and restart Maki; the provider configuration
is read once at startup.
| Field | Notes |
|---|---|
| Issuer URL | For example https://auth.example.com. Maki appends /.well-known/openid-configuration. |
| Client ID / secret | Leave the secret empty for a public client; PKCE protects the exchange either way. |
| Scopes | openid is always requested. Add groups (or your provider’s equivalent) for claim mapping. |
| Create accounts on first sign-in | Off by default. When on, anyone the provider authenticates gets an account. Fine for a household realm; leave it off for a shared company realm. |
| Admin claim / Permission claim | Optional, see below. |
- New accounts start with no library access. Grant a root folder under Settings → Users.
- API keys and the OPDS token need a recent sign-in. An account that signs in only through the provider has no password to confirm, so creating an API key, or turning on OPDS or Komga, needs a sign-in from the last ten minutes instead. The form says so up front and has a Sign in again button that brings you back.
- Linking. An account is identified by the provider’s
subclaim, scoped to the issuer URL, so upstream renames do not strand anyone. The first time an unknown subject signs in, Maki links it to a local account with the same email if the provider marks the address as verified and exactly one account has it. Otherwise it creates an account (if allowed) or refuses. - Claim mapping is all-or-nothing. With both claim fields empty, the provider only says who
someone is and permissions stay as set on the Users page. Fill either one in and the provider
becomes the authority: permissions are recomputed on every sign-in, and edits on the Users page
are overwritten. The admin claim is
claim=value(groups=maki-admins); the permission claim is a claim name whose values are matched against permission names (DownloadChapters,UseOpds, and so on). Unmatched values are ignored, andAdminonly comes from the admin claim. - Require single sign-on refuses password sign-in for everyone except administrators, so a
provider outage never locks you out of your own library. If you are locked out anyway, set
MAKI_ALLOW_LOCAL_LOGIN=1and restart: password sign-in returns for every account, and Maki logs a warning and shows a banner until you remove it. http://issuers are allowed for a provider on the same LAN or Docker network, with a startup warning. Tokens are signed either way, but the discovery document and signing keys travel in the clear. Preferhttps://where you can.