How to set up Mayan EDMS to authenticate against LDAP

Community contributed guides or tutorials for multiple topics like installations for other operating systems or platforms, monitoring, log aggregation, etc.
Post Reply
User avatar
Posts: 213
Joined: Mon Oct 14, 2019 1:18 pm
Location: United Kingdom

How to set up Mayan EDMS to authenticate against LDAP

Post by rssfed23 »

**This draft still has significant room for improvement. Please provide feedback in a reply as to how it worked (or didn't work) in your environment so we can optimise**

I wanted to share a quick guide to configuring LDAP on Mayan EDMS to help get people up and running quickly with LDAP.

There are some existing posts about LDAP, but some of them refer to older versions of Mayan EDMS and are no longer functional.

There are countless ways to configure a LDAP server, so that is outside the scope of this guide. I will be using a free cloud-hosted LDAP server provided by for this walkthrough, primarily because it's free for less than 10 users but also because it can proxy another backend SSO (such as G-Suite) and expose those users over LDAP which fits my use case perfectly. I will highlight areas you will need to consider/make changes for your own environment.
Once these steps have been proven by the community, I will migrate these instructions to the official documentation pages.

The community previously contributed a great example configuration file, which we will use as the basis of our setup.

Edit your docker-compose.yml file and add in the following variables in the environment section:

Code: Select all

      MAYAN_PIP_INSTALLS: python-ldap django_auth_ldap
      MAYAN_APT_INSTALLS: libsasl2-dev python3-dev libldap2-dev libssl-dev libgle3 build-essential autoconf libtool pkg-config gcc
      MAYAN_SETTINGS_MODULE: mayan_settings.myldapfile
For non-compose installs, these variables can be passed in using the -e option (just like how you pass in the database options):

Code: Select all

-e MAYAN_PIP_INSTALLS: python-ldap django_auth_ldap \
-e MAYAN_APT_INSTALLS: libsasl2-dev python3-dev libldap2-dev libssl-dev libgle3 build-essential autoconf libtool pkg-config gcc \
-e MAYAN_SETTINGS_MODULE: mayan_settings.myldapfile
These can be placed under your MAYAN_DATABASES entry. Ensure the correct indentation is retained as all the other environment variables.

Note: for Direct Installs, you can put these environment variables into your supervisor config at /etc/supervisor/conf.d/mayan.conf. Ensure you put a "," at the end of every environment variable you provide to Supervisor. The variables are the same ones used in the docker configuration.

Take note of the MAYAN_SETTINGS_MODULE value. Change the "myldapfile" name to something more relevant to yourself. We will name the configuration file after it later in the section.
You must retain the "mayan_settings." part before whatever you change "myldapfile" to.
Important: You must NOT name "myldapfile" just "ldap". It can be anything but "ldap". This is because we will be using a module later in the guide called "ldap" and conflicts will arise if they're named the same.

Download the example ldap configuration file, and place this into your $MAYAN_MEDIA_ROOT/mayan_settings/ directory.
For Docker installs following the official documentation, this will be /docker-volumes/mayan-edms/media/mayan_settings/

For Direct Installs, this will likely be in /opt/mayan-edms/media/mayan_settings

You must now rename the file so that it's filename matches what you changed "myldapfile" to in the environment variables section earlier.
For example, if my MAYAN_SETTINGS_MODULE value is mayan_settings.rssfed23ldap then the full path to the file should be /docker-volumes/mayan-edms/media/mayan_settings/ It is important to retain the .py file extension.

Next, we need to edit the example configuration file and tweak it to match our LDAP environment. I will walk through some example settings you might want to change here, but the values you need will be entirely dependent on how your LDAP server is set up and they are different for everyone.
Note: You will need to change even more details if you are trying to bind to Microsoft Active Directory. I don't have an AD environment to test against so the community will have to provide this guidance to members

Inside my, the most important settings begin around line 37. These include:

Code: Select all

LDAP_ADMIN_DN = 'uid=bind,ou=Users,o=org,dc=jumpcloud,dc=com'
LDAP_BASE_DN = 'ou=Users,o=org,dc=jumpcloud,dc=com'
LDAP_PASSWORD = 'mybindpassword'
LDAP_URL = 'ldap://'
These settings are going to be unique for your LDAP server. You will have to ensure you have a user with Bind permissions set up, and it is that users Bind password you need to enter above. The ADMIN_DN can be provided by your LDAP administrator.
These values will be different depending on your environment.

I also removed the LDAP_ADDITIONAL_USER_DN line as it's not required for my environment.

The other important part is the AUTH_LDAP_USER_SEARCH line. I recommend everyone read the upstream documentation, as it can help you taylor this file and the parameters in it to your needs. The existing USER_SEARCH line searches both the BASE_DN followed by the ADDITIONAL_USERS_DN, but for my environment those 2 are the same value so it resulted in no results.

So if you get everything set up correctly and you can see in the logs Mayan EDMS is talking to the LDAP server but logins are failing, I would recommend you check the USER_SEARCH parameter and modify it to your needs. Some LDAP environment store the username as the uid value some store it as username and some (like Active Directory) store it as SamAccountName (or similar).

Here's my LDAPSearch:

Code: Select all

    "ou=Users,o=org,dc=jumpcloud,dc=com", ldap.SCOPE_SUBTREE, '(uid=%(user)s)'
The example file is very descriptive and describes a couple of other ways to perform the search, such as using LDAPSearchUnion instead to search within multiple directories.

Finally, you will need to adjust the AUTH_LDAP_USER_ATTR_MAP to match what's shown in your directory.
This is so Mayan can get the correct First/Last name, email etc from the directory and map it to the correct user attributes. Mine is shown below, but yours will almost certainly be different:

Code: Select all

    'user': 'uid',
    'first_name': 'givenName',
    'last_name': 'sn',
    'email': 'mail'
Some users have had to add in their SECRET_KEY (also in the mayan_settings directory) to this file, but I think this is more to do with Active directory or ldaps. I did not require it for my setup.

Before we apply the changes, you must make sure there is an existing user in LDAP with a username matching an admin user in the existing Mayan environment. E.G: create a superuser called "rob" and then ensure that the "rob" user exists in LDAP already. This is because LDAP will become your single point of truth for user authentication and users will no longer be able to login with their existing local credentials and Mayan will map any users with the same username already in the groups/roles DB to ones provided by LDAP, so we need to ensure at least one username with admin capabilities exists so that user can grant other users access.

By default when a user logs into Mayan via LDAP for the first time they will be assigned no groups or roles and will have very limited access to the platform. This is where configuring correct LDAP groups and Mayan roles comes into play, which will be a further extension from this guide out of scope for today. As it stands, users will appear in the user list once they've logged into Mayan EDMS for the first time and someone with suitable rights can assign them the correct group/role from there.
Some users have had success in changing the AUTHENTICATION_BACKENDS line in the configuration file to include both local and LDAP users.

You're now ready to apply the changes. As usual, run a docker-compose down; docker-compose up -d to apply the changes, or "systemctl restart supervisor" for Direct Installs.
You must destroy the existing container as a new one has to be deployed to pick up the APT and PIP installs correctly. If you're not using Docker Compose (and you really should be!) then you can use docker rm -f <mayancontainername> and then do a new "docker run" using the correct environment variables specified above.

Once Mayan EDMS starts again, check you can login with a LDAP user. You will see debug entries in the log for every connection attempt which can be helpful in diagnosing issues. The majority of issues you will encounter are likely to be due to either the right USER_SEARCH string or the relevant base/bind DN settings.

Once confirmed working, you can modify

Code: Select all

ldap.set_option(ldap.OPT_DEBUG_LEVEL, 1)

Code: Select all

ldap.set_option(ldap.OPT_DEBUG_LEVEL, 0)
to disable debug logging.

Again, this is a basic quick start for LDAP. I encourage users to provide their configs/examples below for more advanced configuration. The above example is what we're using on to demonstrate the capability functions as expected, but as LDAP is configured differently for every enterprise your mileage may vary. Don't hesitate to reach out for assistance, and we will log a bug if necessary, but as all ldap functionality is provided by an external module there's not a huge amount we can do within the Mayan EDMS codebase to mitigate issues in upstream code.

Many thanks and good luck!
Please bear with us during the current global situation. The team all have families and local communities to look after as well as the community here. Responses may be delayed during this time, but rest assured we will get to your query eventually.
Posts: 11
Joined: Mon Dec 30, 2019 10:56 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by sna-cmarko »

Thanks for taking the time to write this out, Rob!

I was able to set up LDAP using the Simple Docker method on version 3.3.16. I tested again setting up LDAP using Docker compose for version 3.4.3 on a different machine and it worked well!

I had two tidbits to share with anyone else looking at this process and scratching their head a little. :)

1) When using the Simple Docker install method, pass the variables in this format: -e MAYAN_APT_INSTALLS="libsasl2-dev python3-dev libldap2-dev libssl-dev libgle3 build-essential autoconf libtool pkg-config gcc"

2) Regardless of the Docker install method, set the system up first with your regular settings WITHOUT any LDAP related changes. Create a superuser once the system is up that is the exact username of one of your ldap users. Remove that instance and start with your LDAP related changes. (Rob's example on the superuser was perfect once I understood the order that it should happen.)


Posts: 25
Joined: Wed Sep 05, 2018 3:52 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by lsmoker »

Do you have a recommendation for SSO like SAML or SPNEGO?
Posts: 10
Joined: Fri May 01, 2020 2:26 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by ebotzki »


Your guide helped me a bunch and tomorrow i will add in some things i needed to do to get it to work.

I just had a question. You said you can assign roles and permissions based on ldap groups. What would those settings be to do that and where would you put them? That's the final piece of this puzzle i need to get this working. All i want is a default one for the all users group and give them the ability to read documents.

Posts: 1
Joined: Tue Sep 29, 2020 7:10 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by cristobal.lama »

Thanks, that worked fine for us.
Posts: 11
Joined: Mon Dec 30, 2019 10:56 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by sna-cmarko »

I just tried upgrading from 3.4.17 to 3.5.1. Right now I am seeing this in the logs:

ModuleNotFoundError: No module named 'ldap'

I haven't changed anything in my ldap settings file, until I noticed that there were some additional changes to Python3 in version 3.5 of Mayan.

So far I've tried updating the MAYAN_PIP_INSTALLS to use the pip3 package names, but have not seen any changes in the logs.

Anyone else have this issue and found a solution?

Posts: 1
Joined: Fri Jul 05, 2019 9:04 pm

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by kelvin99 »


I was able to get LDAP authentication working, but I just wanted to revive this topic and ask if anyone has been able to get their LDAP groups pulled into Mayan. I’ve been trying to get that working but I can’t find anywhere that explains the settings for it. If anyone has any information on that, I would greatly appreciate it.

Posts: 3
Joined: Tue Jan 26, 2021 7:05 am

Re: How to set up Mayan EDMS to authenticate against LDAP

Post by spirkaa »

Here is my config:
1. Active Directory
2. Nested group membership resolution (must have for when you implemented RBAC on AD level)
3. Mirroring of specific groups from AD to Django

import ldap

from django_auth_ldap.config import (
LDAPSearch, NestedActiveDirectoryGroupType

from mayan.settings.production import * # noqa

# ... index.html
# ------------------------------------------------------------------------------


ldap.OPT_TIMEOUT: 10,

AUTH_LDAP_BIND_DN = "CN=mayanedmsSvc,OU=Service Accounts,OU=Accounts,OU=Org,DC=corp,DC=example,DC=com"

LDAP_BASE_DN = "OU=Org,DC=corp,DC=example,DC=com"

"username": "sAMAccountName",
"first_name": "givenName",
"last_name": "sn",
"email": "mail",

f"(&(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=CN=MayanEDMS_Users,OU=Security Groups,{LDAP_GROUPS_DN})(sAMAccountName=%(user)s))",

AUTH_LDAP_GROUP_TYPE = NestedActiveDirectoryGroupType()

"MayanEDMS_Read Only",
Post Reply