website/content/docs/admin/ldap-auth.md

+++
title = "LDAP Authentication"
description = "How to use LDAP as your primary way to register and login to BookStack"
date = "2017-01-21"
type = "admin-doc"
+++

BookStack can be configured to allow LDAP based user login. While LDAP login is enabled you cannot log in with the standard user/password login and new user registration is disabled. BookStack will only use the LDAP server for getting user details and for authentication. Data on the LDAP server is not editable through BookStack.

[A video guide for setting up LDAP can be found here](https://foss.video/w/3jKDj5DpF4tqUtx9HhweNM).

### Authentication Setup

When a LDAP user logs into BookStack for the first time their BookStack profile will be created and they will be given the default role set under the 'Default user role after registration' option in the application settings.    

To set up LDAP-based authentication add or modify the following variables in your `.env` file:

```bash
# General auth
AUTH_METHOD=ldap

# The LDAP host, Adding a port is optional
LDAP_SERVER=example.com:389
# If using LDAP over SSL you should also define the protocol:
# LDAP_SERVER=ldaps://example.com:636

# The base DN from where users will be searched within
LDAP_BASE_DN="ou=People,dc=example,dc=com"

# The full DN and password of the user used to search the server
# Can both be left as 'false' (without quotes) to bind anonymously
LDAP_DN="cn=serviceaccount,ou=People,dc=example,dc=org"
LDAP_PASS="my#super#secret#password543"

# A filter to use when searching for users
# The user-provided user-name used to replace any occurrences of '{user}'.
# (Also supported via '${user}' for backwards compatibility.
LDAP_USER_FILTER=(&(uid={user}))

# Set the LDAP version to use when connecting to the server
# Should be set to 3 in most cases.
LDAP_VERSION=3

# Set the property to use as a unique identifier for this user.
# Stored and used to match LDAP users with existing BookStack users.
# Prefixing the value with 'BIN;' will assume the LDAP service provides the attribute value as
# binary data and BookStack will convert the value to a hexidecimal representation.
# Defaults to 'uid'.
LDAP_ID_ATTRIBUTE=uid

# Set the default 'email' attribute. Defaults to 'mail'
LDAP_EMAIL_ATTRIBUTE=mail

# Set the property to use for a user's display name. Defaults to 'cn'.
# Can have multiple attributes listed, separated with a '|' in which 
# case those values will be joined with a space.
# Example: LDAP_DISPLAY_NAME_ATTRIBUTE=given_name|family_name
LDAP_DISPLAY_NAME_ATTRIBUTE=cn

# Set the attribute to use for the user's avatar image.
# Must provide JPEG binary image data.
# Will be used upon login or registration when the user doesn't
# already have an avatar image set.
# Remove this option or set to 'null' to disable LDAP avatar import.
# Note: Using this option can increase the likelihood of errors during login
# due to thumbnail generation which can exhaust available memory in some cases.
LDAP_THUMBNAIL_ATTRIBUTE=jpegphoto

# Force TLS to be used for LDAP communication.
# Use this if you can but your LDAP support will need to support it and
# you may need to import your certificate to the BookStack host machine.
# Defaults to 'false'.
LDAP_START_TLS=false

# Certificate Authority Certificates to use for LDAP TLS connections.
# Generally not needed if using a publicly trusted certificates.
# Value should be a path to a specific CA certificate in pem format,
# or a directory path where certificates are named via hashes, as
# can be managed by a utility like "c_rehash".
# Defaults to 'false'.
#LDAP_TLS_CA_CERT=/etc/ldap/certs

# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
# If using php-fpm, you may want to restart it after changing this option to avoid instability.
#LDAP_TLS_INSECURE=true

# If you need to debug the details coming from your LDAP server, add the below and uncomment (remove the #)
# Only set this option if debugging since it will block logins and potentially show private details.
#LDAP_DUMP_USER_DETAILS=true
```

You will also need to have the php-ldap extension installed on your system. You can change your `APP_DEBUG` variable to `true` while setting up LDAP to make any errors visible. Note that debug mode can expose sensitive details to visitors so you may want to limit access while configuring and you should remember to change this back after LDAP is functioning.

A user in BookStack will be linked to a LDAP user via a 'uid'. If an LDAP user uid changes it can be updated in BookStack by an admin by changing the 'External Authentication ID' field on the user's profile.

You may find that you cannot log in with your initial Admin account after changing the `AUTH_METHOD` to `ldap`. To get around this set the `AUTH_METHOD` to `standard`, login with your admin account then change it back to `ldap`. You get then edit your profile and add your LDAP uid under the 'External Authentication ID' field. You will then be able to login in with that ID.

### Active Directory

BookStack does work with active directory over LDAP. You will likely need to set the below settings for use with AD. Note that the user filter may need to change
depending on your setup and how you manage users in the system. You will still need to follow the setup instructions above.

```bash
LDAP_USER_FILTER=(&(sAMAccountName={user}))
LDAP_VERSION=3
LDAP_ID_ATTRIBUTE=BIN;objectGUID
# Change the below to true if your AD server supports TLS and if your
# BookStack host system will accept the AD provided certificate.
LDAP_START_TLS=false
LDAP_THUMBNAIL_ATTRIBUTE=thumbnailPhoto
```

### LDAP Group Sync

BookStack has the ability to sync LDAP user groups with BookStack roles. By default this will match LDAP group names (typically CN values) with the BookStack role display names with casing ignored.
This can be overridden by via the 'External Authentication IDs' field which can be seen when editing a role while LDAP authentication is enabled. This field can be populated with common names (typically CNs) of accounts *or* groups. If filled, values in this field will be used and the role name will be ignored. You can match on multiple group names by separating them with a comma.  Commas can be escaped with a backslash (`\,`) if you need to map to a group name using a literal comma character.

When matching LDAP groups with role names or 'External Authentication IDs' values, BookStack will standardise the names of ldap groups to be lower-cased and spaces will be replaced with hyphens. For example, to match a LDAP group named "United Kingdom" an 'External Authentication IDs' value of "united-kingdom" could be used.

This feature requires the LDAP server to be able to provide user groups when queried. This is enabled by default on ActiveDirectory via the 'memberOf' attribute but other LDAP systems may need to be configured to enable such functionality. Be aware that the 'memberOf' attribute does not include the user's primary group. If using OpenLDAP you'll need to setup the memberof overlay.

As part of its LDAP group sync functionality, BookStack will also recursively consider the full hierarchy membership of groups.
For example, A user can be a member "Group A", and "Group A" can be a member of "Group B", in which case both "Group A" and "Group B" will be considered for a match to BookStack roles during group sync for that user.

Here are the settings required to be added to your `.env` file to enable group syncing:

```bash
# Enable LDAP group sync, Set to 'true' to enable.
LDAP_USER_TO_GROUPS=true

# LDAP user attribute containing groups, Defaults to 'memberOf'.
LDAP_GROUP_ATTRIBUTE="memberOf"

# Remove users from roles that don't match LDAP groups.
# Note: While this is enabled the "Default Registration Role", editable within the 
# BookStack settings view, will be considered a matched role and assigned to the user.
LDAP_REMOVE_FROM_GROUPS=false

# If you need to debug the group details coming from your LDAP server, add the below and uncomment (remove the #).
# Only set this option if debugging since it will block logins and potentially show private details.
#LDAP_DUMP_USER_GROUPS=true
```