PhotoPrism® Pro lets you authenticate users against a central Lightweight Directory Access Protocol (LDAP) or Active Directory (AD) server so that users on the corporate network can sign in with their existing usernames and passwords. See Environment Variables and CLI Flags for more information on the configuration options.

Config Options

Environment CLI Flag Default Description
PHOTOPRISM_LDAP_URI --ldap-uri LDAP directory URI e.g. ldaps://example.com:636 for LDAP over SSL
PHOTOPRISM_LDAP_CERT --ldap-cert LDAP directory SSL certificate FILE (.pem)
PHOTOPRISM_LDAP_INSECURE --ldap-insecure skip SSL certificate verification when using LDAPS
PHOTOPRISM_LDAP_CHASE --ldap-chase automatically chase referrals when there are multiple LDAP servers
PHOTOPRISM_LDAP_CHASE_INSECURE --ldap-chase-insecure skip SSL certificate verification when chasing referrals
PHOTOPRISM_LDAP_SYNC --ldap-sync update name, email, role, and attributes from LDAP directory on login
PHOTOPRISM_LDAP_BIND --ldap-bind simple LDAP authentication TYPE (simple, md5)
PHOTOPRISM_LDAP_BIND_DN --ldap-bind-dn userprincipalname LDAP username attribute DN e.g. cn or userprincipalname
PHOTOPRISM_LDAP_BASE_DN --ldap-base-dn LDAP directory base DN e.g. dc=example,dc=com
PHOTOPRISM_LDAP_ROLE --ldap-role LDAP default ROLE (admin, user, viewer, contributor, guest), leave blank for none
PHOTOPRISM_LDAP_ROLE_DN --ldap-role-dn custom LDAP group or attribute DN for specifying the role
PHOTOPRISM_LDAP_NOLOGIN --ldap-nologin disable web login for new LDAP users by default
PHOTOPRISM_LDAP_NOLOGIN_DN --ldap-nologin-dn custom LDAP attribute 'DN' to disable web login
PHOTOPRISM_LDAP_WEBDAV --ldap-webdav allow new LDAP users to use WebDAV by default
PHOTOPRISM_LDAP_WEBDAV_DN --ldap-webdav-dn custom LDAP attribute DN to allow WebDAV access
PHOTOPRISM_LDAP_BASE_PATH_DN --ldap-base-path-dn user base path LDAP attribute DN
PHOTOPRISM_LDAP_UPLOAD_PATH_DN --ldap-upload-path-dn user upload path LDAP attribute DN

Attributes in LDAP are not case sensitive, so it doesn't matter if you use upper or lower case for them in the configuration.

Docker Compose Example

services:
  photoprism:
    ...
    environment:
      ## LDAP Authentication
      PHOTOPRISM_LDAP_URI: "ldaps://ldap.example.com:636"
      PHOTOPRISM_LDAP_INSECURE: "false"
      PHOTOPRISM_LDAP_SYNC: "true"
      PHOTOPRISM_LDAP_BIND: "simple"
      PHOTOPRISM_LDAP_BIND_DN: "userprincipalname"
      PHOTOPRISM_LDAP_BASE_DN: "dc=example,dc=com"
      PHOTOPRISM_LDAP_ROLE: ""
      PHOTOPRISM_LDAP_ROLE_DN: "ou=photoprism-*,ou=groups,dc=example,dc=com"
      PHOTOPRISM_LDAP_NOLOGIN: "false"
      PHOTOPRISM_LDAP_WEBDAV: "true"

Server URI & Certificate

The URI of the LDAP or Active Directory server must be specified in the format ldap://hostname:port for plain LDAP and ldaps://hostname:port for LDAPS (LDAP over SSL). For this, the default ports are 389 (LDAP) and 636 (LDAPS).

If the directory server does not have a certificate signed by a trusted certificate authority, you can either set PHOTOPRISM_LDAP_INSECURE to true to ignore SSL certificate errors, or trust a self-signed certificate by specifying a .pem file in the /config/certificates storage folder with PHOTOPRISM_LDAP_CERT.

User Bind DN

The Bind DN (Distinguished Name) is used to identify your account when you authenticate through the LDAP/AD directory server. PhotoPrism also uses it in combination with the Base DN to retrieve and synchronize user attributes such as the email address, display name, and role, if specified. It is usually set to the Common Name (CN) of the account or the UPN (UserPrincipalName) in Active Directory, which is an email-like identifier such as user@example.com. However, UPNs don't necessarily require a valid domain.

Directory Base DN

The Base DN is the starting point when searching for users within the directory. It is commonly set to the domain components (DC) of your organization, for example dc=example,dc=com.

Specifying User Roles

The default role for users authenticated via LDAP/AD can be specified with PHOTOPRISM_LDAP_ROLE.

You can additionally specify a custom role attribute with PHOTOPRISM_LDAP_ROLE_DN, for example photoprismrole. To indicate the role, you can then map the attribute to the name of a valid role in lowercase, for example photoprismrole="viewer". Note that the attribute name is not case sensitive, but the values should be lowercase, e.g. admin, true or false.

Alternatively, you can specify a group DN in PHOTOPRISM_LDAP_ROLE_DN and use * as a placeholder for the role name, e.g. ou=photoprism-*,ou=groups,dc=example,dc=com.

Learn more chevron_right

Custom Attributes

Additional custom user attributes can be specified with the PHOTOPRISM_LDAP_NOLOGIN_DN, PHOTOPRISM_LDAP_WEBDAV_DN, PHOTOPRISM_LDAP_BASE_PATH_DN and PHOTOPRISM_LDAP_UPLOAD_PATH_DN config options. Note that attribute names are not case sensitive in LDAP.

Instead of only providing an attribute name in PHOTOPRISM_LDAP_NOLOGIN_DN and PHOTOPRISM_LDAP_WEBDAV_DN, you can alternatively specifiy a key and value like primaryGroupID=500.

If no custom attribute has been configured or the attribute value is empty, the default will be used.

Command-Line Tools

Troubleshooting

To test the connection to your LDAP/AD server, view user attributes, and troubleshoot problems, you can use the built-in ldap search subcommand, as shown in this example:

docker compose exec photoprism photoprism ldap search -D bob@example.com cn=bob

Users of Red Hat-based Linux distributions can substitute Docker with Podman:

podman-compose exec photoprism photoprism ldap search -D bob@example.com cn=bob

You can combine it with these flags to change the output format, the maximum number of search results and the credentials used for authentication:

Command Flag Description
--md, -m format as machine-readable Markdown
--csv, -c export as semicolon separated values
--tsv, -t export as tab separated values
-n LIMIT LIMIT number of results (default: 100)
-b DN LDAP/AD directory base DN to search e.g. dc=example,dc=com
-D DN the DN to use to bind to the directory server when performing simple authentication
-w PASSWORD the PASSWORD to use to bind to the directory server when performing simple authentication

If you need additional authentication or query options, we recommend using the freely available ldapsearch command, which is included in most Unix-like operating systems as part of the LDAP utilities package.

User accounts authenticated with LDAP/AD can be searched with the following command:

docker compose exec photoprism photoprism ldap ls

Viewing the Current Config Values

To view the current values of all config options, you can run the following:

docker compose exec photoprism photoprism show config

To display all supported config options and their default values:

docker compose exec photoprism photoprism show config-options

Note that our guides use the new docker compose command by default. If your server does not yet support it, the old docker-compose command will still work. Users of Red Hat Enterprise Linux® and compatible Linux distributions such as CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the docker and docker compose commands with podman and podman-compose as drop-in replacements.

PhotoPrism® Documentation

For detailed information on specific product features, services, and related resources, see our Knowledge Base, or read the User Guide for help using the web user interface: