Server Pro: LDAP Config

Available in Overleaf Server Pro is the ability to use a LDAP server to manage users. It is also possible to use with Active Directory systems.

Note, versions of Overleaf Server Pro prior to v0.5.1 used a different LDAP configuration format, see Server Pro: LDAP Config (legacy) for more details.

IMPORTANT: starting with Overleaf CE/Server Pro 5.0.1 environment variables have been rebranded from SHARELATEX_* to OVERLEAF_*.

If you're using a 4.x version (or earlier) please make sure the variables are prefix accordingly (e.g. SHARELATEX_LDAP_URL instead of OVERLEAF_LDAP_URL)

Overleaf Toolkit Users

The Overleaf Toolkit contains a specific section for LDAP configuration.

The information in this page is valid for both Overleaf Toolkit Users and legacy docker-compose.yml users.

Configuration

Internally, Overleaf LDAP uses the passport-ldapauth library. Most of these configuration options are passed through to the server config object which is used to configure passport-ldapauth. If you are having issues configuring LDAP, it is worth reading the README for passport-ldapauth to get a feel for the configuration it expects.

The environment variable EXTERNAL_AUTH=ldap is required to enable the LDAP authentication module.

Environment Variables

• OVERLEAF_LDAP_URL (required) = Url of the LDAP server, E.g. 'ldaps://ldap.example.com:636'

• OVERLEAF_LDAP_EMAIL_ATT = The email attribute the LDAP server will return, defaults to 'mail'

• OVERLEAF_LDAP_NAME_ATT = The property name holding the name of the user which is used in the application

• OVERLEAF_LDAP_LAST_NAME_ATT = If your LDAP server has a first and last name then this can be used in conjuction with OVERLEAF_LDAP_NAME_ATT

• OVERLEAF_LDAP_PLACEHOLDER = The placeholder for the login form, defaults to 'Username'

• OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN = If set to 'true', will update the user first_name and last_name field on each login, and turn off the user-details form on /user/settings page. Otherwise, details will be fetched only on first login.

• OVERLEAF_LDAP_BIND_DN = Optional, e.g. 'uid=myapp,ou=users,o=example.com'.

• OVERLEAF_LDAP_BIND_CREDENTIALS = Password for bindDn.

• OVERLEAF_LDAP_BIND_PROPERTY = Optional, default 'dn'. Property of user to bind against client e.g. 'name', 'email'

• OVERLEAF_LDAP_SEARCH_BASE = The base DN from which to search for users by username. E.g. 'ou=users,o=example.com'

• OVERLEAF_LDAP_SEARCH_FILTER = LDAP search filter with which to find a user by username, e.g. '(uid={{username}})'. Use the literal '{{username}}' to have the given username be interpolated in for the LDAP search. If you are using Active Directory then the search filter '(sAMAccountName={{username}})' may be more appropriate.

• OVERLEAF_LDAP_SEARCH_SCOPE = Optional, default 'sub'. Scope of the search, one of 'base', 'one', or 'sub'.

• OVERLEAF_LDAP_SEARCH_ATTRIBUTES = Optional, default all. Json array of attributes to fetch from LDAP server.

• OVERLEAF_LDAP_GROUP_DN_PROPERTY = Optional, default 'dn'. The property of user object to use in '{{dn}}' interpolation of groupSearchFilter.

• OVERLEAF_LDAP_GROUP_SEARCH_BASE = Optional. The base DN from which to search for groups. If defined, also groupSearchFilter must be defined for the search to work.

• OVERLEAF_LDAP_GROUP_SEARCH_SCOPE = Optional, default 'sub'.

• OVERLEAF_LDAP_GROUP_SEARCH_FILTER = Optional. LDAP search filter for groups. The following literals are interpolated from the found user object: '{{dn}}' the property configured with groupDnProperty. Optionally you can also assign a function instead, which passes a user object, from this a dynamic groupsearchfilter can be retrieved.

• OVERLEAF_LDAP_GROUP_SEARCH_ATTRIBUTES = Optional, default all. Json array of attributes to fetch from LDAP server.

• OVERLEAF_LDAP_CACHE = Optional, default 'false'. If 'true', then up to 100 credentials at a time will be cached for 5 minutes.

• OVERLEAF_LDAP_TIMEOUT = Optional, default Infinity. How long the client should let operations live for before timing out.

• OVERLEAF_LDAP_CONNECT_TIMEOUT = Optional, default is up to the OS. How long the client should wait before timing out on TCP connections.

• OVERLEAF_LDAP_TLS_OPTS_CA_PATH = A JSON array of paths to the CA file for TLS, must be accessible to the docker container. E.g. -env OVERLEAF_LDAP_TLS_OPTS_CA_PATH='["/var/one.pem", "/var/two.pem"]'

• OVERLEAF_LDAP_TLS_OPTS_REJECT_UNAUTH = If 'true', the server certificate is verified against the list of supplied CAs.

LDAP Config Example

At Overleaf, we test the LDAP integration against a test openldap server. The following is an example of a working configuration:

# passed as docker parameters
--env OVERLEAF_LDAP_URL='ldap://ourldapserver:389'
--env OVERLEAF_LDAP_SEARCH_BASE='ou=people,dc=planetexpress,dc=com'
--env OVERLEAF_LDAP_SEARCH_FILTER='(uid={{username}})'
--env OVERLEAF_LDAP_BIND_DN='cn=admin,dc=planetexpress,dc=com'
--env OVERLEAF_LDAP_BIND_CREDENTIALS='GoodNewsEveryone'
--env OVERLEAF_LDAP_EMAIL_ATT='mail'
--env OVERLEAF_LDAP_NAME_ATT='cn'
--env OVERLEAF_LDAP_LAST_NAME_ATT='sn'
--env OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN='true'

# as a docker env file, or in Overleaf Toolkit's "variables.env" file
OVERLEAF_LDAP_URL=ldap://ourldapserver:389
OVERLEAF_LDAP_SEARCH_BASE=ou=people,dc=planetexpress,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(uid={{username}})
OVERLEAF_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=GoodNewsEveryone
OVERLEAF_LDAP_EMAIL_ATT=mail
OVERLEAF_LDAP_NAME_ATT=cn
OVERLEAF_LDAP_LAST_NAME_ATT=sn
OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true

## as part of the "environment" section in a "docker-compose.yml" file
environment:
    OVERLEAF_LDAP_URL: 'ldap://ldap:389'
    OVERLEAF_LDAP_SEARCH_BASE: 'ou=people,dc=planetexpress,dc=com'
    OVERLEAF_LDAP_SEARCH_FILTER: '(uid={{username}})'
    OVERLEAF_LDAP_BIND_DN: 'cn=admin,dc=planetexpress,dc=com'
    OVERLEAF_LDAP_BIND_CREDENTIALS: 'GoodNewsEveryone'
    OVERLEAF_LDAP_EMAIL_ATT: 'mail'
    OVERLEAF_LDAP_NAME_ATT: 'cn'
    OVERLEAF_LDAP_LAST_NAME_ATT: 'sn'
    OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN: 'true'

Testing, Config & Debugging

After bootstrapping Server Pro for the first time, an existing LDAP user must be given admin permissions visiting /launchpad page (or via CLI, but in this case ignoring password confirmation).

LDAP users will appear in Overleaf Admin Panel once they log in first time with their initial credentials.

As LDAP is heavily configurable and flexible by nature it can be a good starting point to have a working example with ldapsearch or even used by another application.

ldapsearch -H ldap://ad.mydomain.com:389 -x -D ENUMuser@mydomain.com -w ENUMpass  -b ou=people,dc=mydomain,dc=com "CN=\*ENUMuser\*" mail