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-docs"
 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 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.
 11
 12 To set up LDAP-based authentication add or modify the following variables in your `.env` file:
 13
 14 ```
 15 # General auth
 16 AUTH_METHOD=ldap
 17
 18 # The LDAP host, Adding a port is optional
 19 LDAP_SERVER=example.com:389
 20 # If using LDAP over SSL you should also define the protocol:
 21 # LDAP_SERVER=ldaps://example.com:636
 22
 23 # The base DN from where users will be searched within.
 24 LDAP_BASE_DN=ou=People,dc=example,dc=com
 25
 26 # The full DN and password of the user used to search the server
 27 # Can both be left as false to bind anonymously
 28 LDAP_DN=false
 29 LDAP_PASS=false
 30
 31 # A filter to use when searching for users
 32 # The user-provided user-name used to replace any occurrences of '${user}'
 33 LDAP_USER_FILTER=(&(uid=${user}))
 34
 35 # Set the LDAP version to use when connecting to the server.
 36 LDAP_VERSION=false
 37
 38 # Set the default 'email' attribute. Defaults to 'mail'.
 39 LDAP_EMAIL_ATTRIBUTE=mail
 40 ```
 41
 42 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.
 43
 44 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.
 45
 46 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.