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 editable through BookStack.
   9
  10 [A video guide for setting up LDAP can be found here](https://foss.video/w/3jKDj5DpF4tqUtx9HhweNM).
  11
  12 ### Authentication Setup
  13
  14 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.
  15
  16 To set up LDAP-based authentication add or modify the following variables in your `.env` file:
  17
  18 ```bash
  19 # General auth
  20 AUTH_METHOD=ldap
  21
  22 # The LDAP host, Adding a port is optional
  23 LDAP_SERVER=example.com:389
  24 # If using LDAP over SSL you should also define the protocol:
  25 # LDAP_SERVER=ldaps://example.com:636
  26
  27 # The base DN from where users will be searched within
  28 LDAP_BASE_DN="ou=People,dc=example,dc=com"
  29
  30 # The full DN and password of the user used to search the server
  31 # Can both be left as 'false' (without quotes) to bind anonymously
  32 LDAP_DN="cn=serviceaccount,ou=People,dc=example,dc=org"
  33 LDAP_PASS="my#super#secret#password543"
  34
  35 # A filter to use when searching for users
  36 # The user-provided user-name used to replace any occurrences of '{user}'.
  37 # (Also supported via '${user}' for backwards compatibility.
  38 LDAP_USER_FILTER=(&(uid={user}))
  39
  40 # Set the LDAP version to use when connecting to the server
  41 # Should be set to 3 in most cases.
  42 LDAP_VERSION=3
  43
  44 # Set the property to use as a unique identifier for this user.
  45 # Stored and used to match LDAP users with existing BookStack users.
  46 # Prefixing the value with 'BIN;' will assume the LDAP service provides the attribute value as
  47 # binary data and BookStack will convert the value to a hexidecimal representation.
  48 # Defaults to 'uid'.
  49 LDAP_ID_ATTRIBUTE=uid
  50
  51 # Set the default 'email' attribute. Defaults to 'mail'
  52 LDAP_EMAIL_ATTRIBUTE=mail
  53
  54 # Set the property to use for a user's display name. Defaults to 'cn'
  55 LDAP_DISPLAY_NAME_ATTRIBUTE=cn
  56
  57 # Set the attribute to use for the user's avatar image.
  58 # Must provide JPEG binary image data.
  59 # Will be used upon login or registration when the user doesn't
  60 # already have an avatar image set.
  61 # Remove this option or set to 'null' to disable LDAP avatar import.
  62 LDAP_THUMBNAIL_ATTRIBUTE=jpegphoto
  63
  64 # Force TLS to be used for LDAP communication.
  65 # Use this if you can but your LDAP support will need to support it and
  66 # you may need to import your certificate to the BookStack host machine.
  67 # Defaults to 'false'.
  68 LDAP_START_TLS=false
  69
  70 # Certificate Authority Certificates to use for LDAP TLS connections.
  71 # Generally not needed if using a publicly trusted certificates.
  72 # Value should be a path to a specific CA certificate in pem format,
  73 # or a directory path where certificates are named via hashes, as
  74 # can be managed by a utility like "c_rehash".
  75 # Defaults to 'false'.
  76 #LDAP_TLS_CA_CERT=/etc/ldap/certs
  77
  78 # If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
  79 # Only set this option if debugging or you're absolutely sure it's required for your setup.
  80 # If using php-fpm, you may want to restart it after changing this option to avoid instability.
  81 #LDAP_TLS_INSECURE=true
  82
  83 # If you need to debug the details coming from your LDAP server, add the below and uncomment (remove the #)
  84 # Only set this option if debugging since it will block logins and potentially show private details.
  85 #LDAP_DUMP_USER_DETAILS=true
  86 ```
  87
  88 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.
  89
  90 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.
  91
  92 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.
  93
  94 ### Active Directory
  95
  96 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
  97 depending on your setup and how you manage users in the system. You will still need to follow the setup instructions above.
  98
  99 ```bash
 100 LDAP_USER_FILTER=(&(sAMAccountName={user}))
 101 LDAP_VERSION=3
 102 LDAP_ID_ATTRIBUTE=BIN;objectGUID
 103 # Change the below to true if your AD server supports TLS and if your
 104 # BookStack host system will accept the AD provided certificate.
 105 LDAP_START_TLS=false
 106 LDAP_THUMBNAIL_ATTRIBUTE=thumbnailPhoto
 107 ```
 108
 109 ### LDAP Group Sync
 110
 111 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.
 112 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.
 113
 114 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.
 115
 116 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.
 117
 118 As part of its LDAP group sync functionality, BookStack will also recursively consider the full hierarchy membership of groups.
 119 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.
 120
 121 Here are the settings required to be added to your `.env` file to enable group syncing:
 122
 123 ```bash
 124 # Enable LDAP group sync, Set to 'true' to enable.
 125 LDAP_USER_TO_GROUPS=true
 126
 127 # LDAP user attribute containing groups, Defaults to 'memberOf'.
 128 LDAP_GROUP_ATTRIBUTE="memberOf"
 129
 130 # Remove users from roles that don't match LDAP groups.
 131 # Note: While this is enabled the "Default Registration Role", editable within the
 132 # BookStack settings view, will be considered a matched role and assigned to the user.
 133 LDAP_REMOVE_FROM_GROUPS=false
 134
 135 # If you need to debug the group details coming from your LDAP server, add the below and uncomment (remove the #).
 136 # Only set this option if debugging since it will block logins and potentially show private details.
 137 #LDAP_DUMP_USER_GROUPS=true
 138 ```