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 comes with flexible authentication features. It can handle user accounts, groups, permissions. Papermerge supports following authentication modes:

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

Built-in

By default Papermerge 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 internal components.

Built-in authentication mechanism is suitable for simple setups when Papermerge 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 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 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 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 will connect to LDAP server using secure TLS connection. If you want Papermerge 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 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 uses ldap3 python package to perform LDAP authentication. Here is source code of ldap authentication part.

By default Papermerge 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 about email attribute in LDAP entry with PAPERMERGE__AUTH__LDAP_URL.