Skip to content

Authentication

This section briefly describes authentication. It focuses mostly on relevant settings so that you can quickly set it up.

For detailed information about each method as well as how to configure it with specific identity provider check SSO documentation.

Papermerge DMS comes with flexible authentication features. It can handle user accounts, groups, permissions. Papermerge DMS supports following authentication modes:

  • Built-in
  • OpenID Connect (OIDC)
  • Remote User
  • LDAP

Built-in

By default Papermerge DMS will use built-in authentication mechanism. You only need to provide PAPERMERGE__AUTH__USERNAME, PAPERMERGE__AUTH__PASSWORD environment variables. In this mode there is no external party involved as all authentication is performed by Papermerge DMS internal components.

Built-in authentication mechanism is suitable for simple setups when Papermerge DMS is your only application of concern.

When you want to give users access to multiple applications using same accounts, you may consider:

OpenID Connect (OIDC)

Papermerge DMS supports OpenID Connect (OIDC) authentication.

In order to enable OIDC authentication you need to provide following environment variables:

  • PAPERMERGE__AUTH__OIDC_CLIENT_SECRET
  • PAPERMERGE__AUTH__OIDC_CLIENT_ID
  • PAPERMERGE__AUTH__OIDC_AUTHORIZE_URL
  • PAPERMERGE__AUTH__OIDC_ACCESS_TOKEN_URL
  • PAPERMERGE__AUTH__OIDC_USER_INFO_URL
  • PAPERMERGE__AUTH__OIDC_LOGOUT_URL
  • PAPERMERGE__AUTH__OIDC_INTROSPECT_URL
  • PAPERMERGE__AUTH__OIDC_REDIRECT_URL

Note that last one, redirect URL, is the only URL pointing to Papermerge DMS instance domain. It should have following format <http|https>://<papermerge-instance-domain>/oidc/callback. Example:

PAPERMERGE__AUTH__OIDC_REDIRECT_URL=https://papermerge.net/oidc/callback

All other URLs, authorize URL, access point URL, user info URL, introspect URL and logout URL, should point to OIDC provider domain. Examples:

PAPERMERGE__AUTH__OIDC_CLIENT_SECRET=pT5Ff-your-token-eWOSvEPmtyY
PAPERMERGE__AUTH__OIDC_CLIENT_ID=papermerge
PAPERMERGE__AUTH__OIDC_AUTHORIZE_URL=http://keycloak.trusel.net:8080/realms/myrealm/protocol/openid-connect/auth
PAPERMERGE__AUTH__OIDC_ACCESS_TOKEN_URL=http://keycloak.trusel.net:8080/realms/myrealm/protocol/openid-connect/token
PAPERMERGE__AUTH__OIDC_USER_INFO_URL=http://keycloak.trusel.net:8080/realms/myrealm/protocol/openid-connect/userinfo
PAPERMERGE__AUTH__OIDC_LOGOUT_URL=http://keycloak.trusel.net:8080/realms/myrealm/protocol/openid-connect/logout
PAPERMERGE__AUTH__OIDC_INTROSPECT_URL=http://keycloak.trusel.net:8080/realms/myrealm/protocol/openid-connect/token/introspect

For detailed information OpenID Connect see SSO/OIDC documentation.

Remote User

LDAP

Papermerge DMS can perform authentication against users stored in LDAP system. In order to enable LDAP authentication you need to provide at least two environment variables:

First one is the URL to your ldap server, without scheme, example:

PAPERMERGE__AUTH__LDAP_URL=ldap.trusel.net

By default, Papermerge DMS will connect to LDAP server using secure TLS connection. If you want Papermerge DMS to access LDAP server using plain text connection, set PAPERMERGE__AUTH__LDAP_USE_SSL to False:

PAPERMERGE__AUTH__LDAP_USE_SSL=False

The second mandatory option is PAPERMERGE__AUTH__LDAP_USER_DN_FORMAT. It instructs Papermerge DMS the DN (distinguished name) of the user you want to authenticate against. Example:

PAPERMERGE__AUTH__LDAP_USER_DN_FORMAT=uid={username},ou=People,dc=ldap,dc=trusel,dc=net

Notice "{username}" part - it must be literaly this value; the "{username}" will be replaced with actual username of the user when performing LDAP bind.

Info

In case you are curious, Papermerge DMS uses ldap3 python package to perform LDAP authentication. Here is source code of ldap authentication part.

By default Papermerge DMS will try to extract user's email from mail attribute of LDAP entry identified PAPERMERGE__AUTH__LDAP_USER_DN_FORMAT distinguished name. You can instruct Papermerge DMS about email attribute in LDAP entry with PAPERMERGE__AUTH__LDAP_URL.