Microsoft Active Directory

Security Risks

By using AD/LDAP for authentication, you need to be aware that passwords are sent to the grape server in clear text and transmitted to the LDAP server. This means, if the Grape server is compromised, the attacker could log passwords of users at the login and compromise other systems with those credentials.

We therefore recommend to use our SSO feature for authentication because passwords never reach the Grape server but only the SSO IDP. This is recommended for any software in a company to keep user passwords secure.


  1. You need to be admin or owner of the Organization, in order to manage LDAP

  2. You need an Active Directory that can be reached from the Grape instance

  3. You need a AD User to use for binding via LDAP with sufficient privileges

  4. Pagination has to be enabled (we use a page size of 100 by default)

  5. The bind user must be able to see Users you want to import and get the following attributes:

    • name

    • sAMAccountName

    • cn

    • sn

    • givenName

    • mail

    • company

    • department

    • member

    • memberOf

    • objectClass

    • uSNChanged

    • userAccountControl

    • accountExpires

    • objectSid

    • objectGUID

    and be able to read the groups that are specified by the memberOf of the user. Grape will only read the groups’ name by querying each group’s DN individually. This is especially relevant for the CIFS integration which will crawl through the groups recursively in order to determine file access permissions.

Enable LDAP for an Organization

  1. Go the admin site (

  2. Click on “Organizations”

  3. Click on the organization that needs LDAP

  4. Scroll down to “Features”

  5. Select “Active Directory” From the drop-down menu

  6. Scroll down to the bottom

  7. Press “Save”

Configure LDAP

In the Web Client or in your Desktop Client:

  1. Click the cogwheel cogwheel

  2. Click “Organization Settings”

  3. Click on “LDAP Settings” in the menu on the left (this option is only available after you enabled LDAP in the admin site!)

  4. When you enter this page for the first time, you will be redirected to the LDAP Connection creation page Enter the LDAP bind credentials there. The form will only save if a connection could be established successfully.

The defaults in User Filter and Group Filter are normally correct for AD. Make sure the LDAP Type is set tp Active Directory.

It’s important that you proper configure the field “Default action for removed user” ad this action will be taken when removing users from AD. See remove user documentation for more details.

Please make sure to use a read-only service user for this connection. This user’s credentials will be stored in recoverable encrypted form for later background synchronization.

Note: If ldaps is used and the AD Server is using a self-signed certificate, the connection will fail (Cannot reach the AD Server) You need to disable the certificate check for the python-ldap module, by adding the following environment variable to /data/grape/config/application/grape-extra.env: LDAPTLS_REQCERT=never

Importing Users and Groups

Click the users icon users icon

You can add as many AD user sources as you want (OUs or AD Groups), by adding their DNs respectively. For each Import source you get to chose if the user import should be recursive or just flatly in the specified DN.

Implementation Details


We get all objects that are of objectClass=person within the specified OU (and all underlying OUs if you chose recursive).

AD Groups

First we get the single object of the group and read all DNs in the member attribute. From this we find the biggest common denominator (bcd) that all members in the Group share. Next we make a LDAP query asking for all Users that have the memberOf relation to that AD Group and limit the search to the bcd . If recursive is turned on for the AD Group, we will also find groups that have that memberOf attribute and repeat the operation.

Locked users

Users that are locked in the AD (either ACCOUNTLOCKED flag or account expire date timestamp in the past) will not be initially imported. If users are already imported and are flagged locked at a later synchronization, will be disabled in the organization.

Unlocking works the same way: Users that where locked and are unlocked in AD will become unlocked in grape right after the next synchronization.

Syncronisation time and status

The synchronization of user and group data via LDAP happens asynchronously in the background. Depending on what other background processes are running, the synchronization can be queued for some time.

You can see the “sync status” and the last time a source was successfully synced for each import. If a sync failed, the sync status usually reveals an error message.

By default the resync will happen once every 60 Minutes. This can be edited by setting a new value in LDAP_FULL_RESYNC_MINUTES in the grape-extra.env