LucidWorks Enterprise supports integrating user authentication with an existing LDAP system. Two LDAP features are currently supported.
- Authentication and Authorization of users (prerequisite for any other LDAP functionality)
- User to group mapping (optional)
At this time, LDAP and built-in (API-based) user authentication are mutually exclusive. If LDAP is enabled, built-in authentication is not, and the reverse.
 | Self-signed Certificates At this time, LucidWorks Enterprise LDAP functionality is not compatible with self-signed or custom certificates. |
To configure LucidWorks Enterprise to use LDAP for user authentication, first edit the LDAP Configuration File, then use the Authentication Screen in the Admin UI to test the configuration before enabling it. The Authentication screen allows you to load the configuration to LucidWorks Enterprise and enable LDAP without restarting the server.
LDAP Configuration File
The main configuration file for configuring LDAP is $LWE_HOME/conf/ldap-config.yml. The default settings must be modified as needed for LucidWorks Enterprise to connect to the LDAP server and query the database for user authentication. After the file has been edited, either restart the server or go to the Authentication page in the UI to load the configuration without a server restart.
It is a good idea to leave the :enabled: false setting as false until the connection details have been tested via the Authentication page in the Admin UI and at least one valid LDAP user has been allowed authorization to the Admin UI. If LDAP has accidentally been enabled before testing and no users have been allowed access to the Admin UI, change :enabled: true back to false and restart the server to be able to get back into the system.
 | Map a Valid LDAP User/Group to Authorization Before Enabling LDAP Because LucidWorks Enterprise's built-in authentication is disabled when LDAP authentication is enabled, it would not be possible to map a user or group to the Admin authorization after LDAP is enabled. If no one has Admin authorization, no one will be able to access the Administration User Interface. So, before enabling LDAP, go to the System page and map an LDAP username or a group to "Admin UI" by adding it to the Group or User section of the Admin UI definition. For more information about Group or User mappings to authorizations, see Configuring UI Authorization. |
Below is the default content of the ldap-config.yml file.
production: :enabled: false :verbose_logging: # defaults to false :ssl: # defaults to false :host: # default = 'localhost' :port: # defaults to standard or SSL LDAP port, as appropriate # If ldap location of users is fixed # then search base, bind_id and bind_pwd can be omitted, and user_base supplied instead :user_base: # e.g. 'uid=$USER,ou=people,dc=example,dc=com' # Otherwise, if users can be at different points in the directory # then bind credentials with search permission are necessary :bind_id: 'cn=root,dc=example,dc=com' :bind_pwd: 'password' :search_base: 'dc=example,dc=com' :user_filter: 'uid=$USER' # you can specify group membership by adding groups as attributes to user objects :group_attr_for_user: # e.g. 'memberOf'; default = nil; attribute of user specifying membership in group # or you can specify group membership by adding users as attributes to group objects :group_filter: '(&(objectclass=groupOfNames)(member=$USER))' :user_attr_for_group: # default = 'dn'; attribute of user specified as value of a group membership attribute :user_attr_for_lwe: # default = 'cn'; attribute of group specified in LWE authorizations and search filters
The ldap-config.yml file also includes the following configuration for use with Windows Active Directory. This section is commented out in ldap-config.yml. The primary differences between the default LDAP configuration settings and the Active Directory settings are the values for the user_filter and group_filter attributes:
:production # The following is a complete sample config for integrating with an Active Directory server # Pay particular attention to the user_filter and group_filter attributes here # Also note the lack of a "user_base" value :host: 'ldap.corp.net', :port: nil, :bind_id: 'cn=admin,cn=users,dc=corp,dc=net', :bind_pwd: 'secret', :search_base: 'dc=corp,dc=net', :user_filter: 'userPrincipalName=$USER', :group_filter: '(&(objectclass=group)(member=$USER))', :group_attr_for_lwe: 'cn'
Editing the setting :verbose_logging: to true will enable detailed information about LDAP queries to appear in the ui.log file found in $LWE_HOME/data/logs directory. This can be very useful in debugging problems with an initial LDAP configuration. However, this setting will log details about every LDAP query, which may cause the ui.log to swell in a production environment, and may expose user or group information and create an additional security concern. Be sure to change this setting to false and reload the configuration on the Authentication screen once LDAP has been successfully enabled.
User to Group Mappings
LWE supports two different methods of mapping users to groups:
- Listing users as attributes in group directory entries
- Listing groups as attributes in user directory entries
You should only use one of these methods at a time. Your configuration should contain only one of the two blocks of LDAP user/group mapping settings.
Using the Authentication Screen
After you have entered LDAP connection details into the LDAP configuration file, you can use the UI to test the configuration prior to enabling it. To use this screen, enter a username and password that is valid in the LDAP system, then click Test.
The screen will show the results of the test on the left side, under the boxes for username and password.
If configuration changes are required, make the changes to the $LWE_HOME/conf/ldap-config.yml file on the server, then click Reload and repeat the test until it is successful. Once confident that the configuration will work as intended, change :enabled: false to :enabled: true, return to this page and click Reload. Before doing this, be sure at least one valid LDAP user has been given authorization to use the Admin UI.
When LDAP is enabled and the configuration reloaded, all active users may get an error message and will need to log in again with their LDAP credentials (unless their built-in username matches their LDAP username).
Manual User Management
Instead of using LDAP to authenticate users, LucidWorks Enterprise includes a REST API that allows creation of users. Using this API and the Perl Examples provided with the application, users can be created, passwords reset, and accounts deleted.