Skip to content

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 sub claim, 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, and Admin only 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=1 and 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. Prefer https:// where you can.