LDAP

Server Pro provides LDAP server integration for user authentication and is compatible with Active Directory systems. For Toolkit deployments, the LDAP integration is configured via the config/variables.env file.

Overview

Internally, the LDAP integration 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.

To enable LDAP authentication the EXTERNAL_AUTH variable must be set to ldap:

EXTERNAL_AUTH=ldap

After bootstrapping Server Pro for the first time with LDAP authentication, an existing LDAP user must be given admin permissions by visiting the /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.

To preserve backward compatibility with older configuration files, if EXTERNAL_AUTH is not set, but OVERLEAF_LDAP_URL is set, then the LDAP module will be activated. We still recommend setting EXTERNAL_AUTH explicitly.

Configuration

Name	Description
OVERLEAF_LDAP_URL	Required, The 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 conjunction 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=admin,ou=people,o=planetexpress.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=people,o=planetexpress.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 in milliseconds before timing out.
OVERLEAF_LDAP_CONNECT_TIMEOUT	Optional, default is up to the OS. How long the client should wait in milliseconds 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.
OVERLEAF_LDAP_IS_ADMIN_ATT and OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE	When both environment variables are set, the login process updates user.isAdmin = true when the profile returned by LDAP contains OVERLEAF_LDAP_IS_ADMIN_ATT, and its value is either equals to OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE, or an array containing OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE. Introduced: 5.2.0

Example configuration

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

# added to variables.env

EXTERNAL_AUTH=ldap
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

The openldap needs to run in the same network as the sharelatex container (which by default would be overleaf_default), so we'll proceed with the following steps:

• Run docker network create overleaf_default (will possibly fail due to a network with name overleaf_default already exists error, that's OK).

• Start openldap container with docker run --network=overleaf_default --name=ldap rroemhild/test-openldap:1.1

• Edit variables.env to add the LDAP environment variables as listed above.

• Run bin/up -d and you should be able to login using fry as both username and password.

Debugging

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.

The following command will connect to the LDAP server at ldap on port 389. It will then bind to the server using the distinguished name (DN) [e-mail] and password password123. The base DN for the search will be ou=people,dc=planetexpress,dc=com. The search filter is set to return entries where the Common Name (CN) contains fry, and it will return the mail attribute of these entries.

When running this search command against your own service please ensure that you replace fry, password123, and planetexpress.com with your actual username, password, and domain. Also, make sure that the LDAP server is accessible and the provided details are correct:

ldapsearch -H ldap://ldap:389 -x -D [e-mail] -w password123 -b ou=people,dc=planetexpress,dc=com "CN=*fry*" mail