Running an OpenID-Connect Provider like Kanidm has many advantages, of of them being able to configure it as Single-Sign-On (SSO) for apps that would otherwise require you to have a different set of credentials for each app/account.

I have a working Paperless-ngx running holding about a thousand documents, and it has been great so far. But SSO has always been something that was missing yet. So when I got myself a Kanidm I set out to change that.

Kanidm 1.10.4 running at https://idm.skowalak.de
Paperless-ngx v2.20.15 running at https://paperless.skowalak.de

This is the basic config I had before starting (simplified for brevity):

 1{ config, ... }:
 2{
 3  sops = {
 4    secrets = { };
 5    templates."paperless.env" = { };
 6  };
 7
 8  services.nginx.virtualHosts."paperless.skowalak.de" = {
 9    forceSSL = true;
10    locations."/".proxyPass = "http://localhost:28981";
11  };
12
13  services.paperless = {
14    enable = true;
15
16    settings = {
17      PAPERLESS_URL = "https://paperless.skowalak.de";
18    };
19    environmentFile = config.sops.templates."paperless.env".path;
20  };
21}

Configure Kanidm

I wanted to connect my Kanidm account sebastian@idm.skowalak.de to my Paperless-ngx account sebastian. Both accounts did already exist. So on the Kanidm side the following config was added by using the kanidm cli:

kanidm group create paperless_users
# Successfully created group 'paperless_users'

kanidm group add-members paperless_users sebastian
# Successfully added ["sebastian"] to group "paperless_users"

kanidm system oauth2 create paperless 'Paperless-ngx' 'https://paperless.skowalak.de'
# Success

kanidm system oauth2 add-redirect-url paperless 'https://paperless.skowalak.de/accounts/oidc/kanidm/login/callback/'
# Success

kanidm system oauth2 update-scope-map paperless paperless_users openid profile email
# Success

kanidm system oauth2 prefer-short-username paperless
# Success

kanidm system oauth2 show-basic-secret paperless
# <redacted>

So far so uninteresting, only the second-to-last command is actually interesting. By setting prefer-short-username we tell Kanidm not to use the full Security Principal Name (SPN), which in this case would be sebastian@idm.skowalak.de but instead use the short version without the domain: sebastian.

Configure Paperless

The OIDC client secret is added to sops-nix.

1paperless:
2  kanidm_client_secret: <redacted>

Then the Paperless-ngx config is amended. Paperless-ngx does OIDC through the openid_connect provider from django-allauth.

 1{ config, ... }:
 2{
 3  sops = {
 4    secrets = {
 5      "paperless/kanidm_client_secret" = { };
 6    };
 7    templates."paperless.env" = {
 8      content = ''
 9        PAPERLESS_SOCIALACCOUNT_PROVIDERS='{"openid_connect":{"OAUTH_PKCE_ENABLED":true,"APPS":[{"provider_id":"kanidm","name":"Kanidm","client_id":"paperless","secret":"${
10          config.sops.placeholder."paperless/kanidm_client_secret"
11        }","settings":{"server_url":"https://idm.skowalak.de/oauth2/openid/paperless/.well-known/openid-configuration"}}],"SCOPE":["openid","profile","email"]}}'
12      '';
13      owner = config.services.paperless.user;
14    };
15  };
16
17  # omitted nginx config here, because nothing changed
18
19  services.paperless = {
20    enable = true;
21
22    settings = {
23      PAPERLESS_APPS = "allauth.socialaccount.providers.openid_connect";
24
25      # Disable local self-registration but allow remote registration in
26      # Kanidm.
27      PAPERLESS_ACCOUNT_ALLOW_SIGNUPS = false;
28      PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS = true;
29      PAPERLESS_SOCIAL_ACCOUNT_DEFAULT_GROUPS = "users";
30
31      # After everything is verified to work, these two switches can be turned
32      # on to hide the Paperless-ngx login screen and instead redirect to
33      # Kanidm directly.
34      PAPERLESS_REDIRECT_LOGIN_TO_SSO = false;
35      PAPERLESS_DISABLE_REGULAR_LOGIN = false;
36
37      PAPERLESS_URL = "https://paperless.skowalak.de";
38    };
39    environmentFile = config.sops.templates."paperless.env".path;
40  };
41}

Finally, Paperless-ngx user accounts need to be linked to their Kanidm account counterparts. This is done by logging into Paperless-ngx with old credentials, goint into profile settings and clicking on Kanidm under Connect new social account. After that, first party Paperless-ngx login can be disabled.