Setting up Single Sign-On (SSO)
You can configure your Paperless-ngx instance so that users sign in via Single Sign-On (SSO) against your identity provider. Paperless-ngx supports the OpenID Connect standard for this — so it works with Authentik, Keycloak, Zitadel, Google Workspace, Microsoft Entra ID, and other OIDC providers.
- An active Paperless-ngx subscription at server.camp
- A reachable, OIDC-capable identity provider instance
- Admin access to both systems
Create a new OAuth2/OpenID application for Paperless-ngx at your identity provider. The exact procedure differs per provider. Enter the following redirect URI there:
https://<your-paperless-domain>/accounts/oidc/sso/login/callback/
The sso path segment is fixed and independent of the provider name you choose later. If you use a custom domain for Paperless-ngx, add its callback URL as well.
Finally, note down the client ID, the client secret, and the OpenID configuration URL (also called “discovery URL” or “well-known URL”). This is the URL under which /.well-known/openid-configuration is reachable, e.g.:
https://your-authentik.srv.camp/application/o/paperless/.well-known/openid-configuration
Restrict access by groupAt your IdP, restrict access to the application to a specific group (e.g.all-employees). Only members of that group will be able to sign in to Paperless-ngx via SSO.
In the customer portal, open the configuration of your Paperless-ngx subscription and enter these values:
| Field | Value |
|---|---|
| Enable Single Sign-on | Checked |
| Provider name | Freely chosen, e.g. Authentik – shown as the label of the login button |
| Client ID | Copied from your IdP |
| Client secret | Copied from your IdP |
| OpenID configuration endpoint | Discovery URL from Step 1 |
Save and wait for the deployment to finish (about 1–2 minutes). The Paperless-ngx login page then shows an additional button to sign in via your provider.
The following fields are optional. Only set them if you specifically need to deviate from the default behaviour:
| Field | Default | Effect |
|---|---|---|
| Allow sign-ups | Unchecked | Lets new users register themselves via OpenID Connect. Without this option, only existing accounts can sign in. |
| Use provider sign-up form | Unchecked | Skips the Paperless-ngx registration dialog and takes name, email, etc. directly from the identity provider. |
| Sync groups | Unchecked | Adds or removes users from the matching Paperless groups based on their group membership at the IdP. The groups must already exist in Paperless-ngx. |
| Default groups | – | Comma-separated list of groups new users are assigned to automatically. The groups must be created manually beforehand. |
| Logout redirect URL | – | URL to redirect to after logout (e.g. your provider’s logout form). |
- Open Paperless-ngx in the browser
- On the login page, click the button for your provider
- Redirect to the IdP, sign in there
- Back in Paperless-ngx — the user is signed in
Test before switching overThe classic login form remains available next to the SSO button. This lets you sign in with your local admin account if the configuration needs adjusting.
- “redirect_uri mismatch” at the IdP: check that the redirect URI is stored exactly — including path (
/accounts/oidc/sso/login/callback/) and trailing slash. - No SSO button visible: is “Enable Single Sign-on” checked and has the deployment in the portal finished?
- Login fails with “account does not exist”: enable “Allow sign-ups” so new users can sign in via SSO, or create the account in Paperless-ngx beforehand.
If you have any further questions, reach our support via the customer portal.