BookStack Code Mirror - website/blob - content/docs/admin/ldap-auth.md

 1 +++
 2 title = "LDAP Authentication"
 3 description = "How to use LDAP as your primary way to register and login to BookStack"
 4 date = "2017-01-21"
 5 type = "admin-doc"
 6 +++
 7
 8 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 currently editable through BookStack.
 9
 10 ### Authentication Setup
 11
 12 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.
 13
 14 To set up LDAP-based authentication add or modify the following variables in your `.env` file:
 15
 16 ```bash
 17 # General auth
 18 AUTH_METHOD=ldap
 19
 20 # The LDAP host, Adding a port is optional
 21 LDAP_SERVER=example.com:389
 22 # If using LDAP over SSL you should also define the protocol:
 23 # LDAP_SERVER=ldaps://example.com:636
 24
 25 # The base DN from where users will be searched within.
 26 LDAP_BASE_DN=ou=People,dc=example,dc=com
 27
 28 # The full DN and password of the user used to search the server
 29 # Can both be left as false to bind anonymously
 30 LDAP_DN=false
 31 LDAP_PASS=false
 32
 33 # A filter to use when searching for users
 34 # The user-provided user-name used to replace any occurrences of '${user}'
 35 LDAP_USER_FILTER=(&(uid=${user}))
 36
 37 # Set the LDAP version to use when connecting to the server.
 38 LDAP_VERSION=false
 39
 40 # Set the default 'email' attribute. Defaults to 'mail'.
 41 LDAP_EMAIL_ATTRIBUTE=mail
 42 ```
 43
 44 You will also need to have the php-ldap extension installed on your system. It's recommended to change your `APP_DEBUG` variable to `true` while setting up LDAP to make any errors visible. Remember to change this back after LDAP is functioning.
 45
 46 A user in BookStack will be linked to a LDAP user via a 'uid'. If a 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.
 47
 48 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.
 49
 50 ### Active Directory
 51
 52 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
 53 depending on your setup and how you manage users in the system. You will still need to follow the setup instructions above.
 54
 55 ```bash
 56 LDAP_USER_FILTER=(&(sAMAccountName=${user}))
 57 LDAP_VERSION=3
 58 ```
 59
 60 ### LDAP Group Sync
 61
 62 BookStack has the ability to sync LDAP user groups with BookStack roles. By default this will match LDAP group names with the BookStack role display names with casing ignored.
 63 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 distinguished names (DNs) of accounts *or* groups. If filled, DNs in this field will be used and the role name will be ignored. You can match on multiple DNs by separating them with a comma.
 64
 65 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. If using OpenLDAP you'll need to setup the memberof overlay.
 66
 67 Here are the settings required to be added to your `.env` file to enable group syncing:
 68
 69 ```bash
 70 # Enable LDAP group sync, Set to 'true' to enable.
 71 LDAP_USER_TO_GROUPS=true
 72
 73 # LDAP user attribute containing groups, Defaults to 'memberOf'.
 74 LDAP_GROUP_ATTRIBUTE="memberOf"
 75
 76 # Remove users from roles that don't match LDAP groups.
 77 LDAP_REMOVE_FROM_GROUPS=false
 78 ```