LucidWorks 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)
LDAP and built-in (API-based) user authentication are mutually exclusive. If LDAP is enabled, built-in authentication is not, and the reverse.
To configure LucidWorks to use LDAP for user authentication, edit the LDAP Configuration File, then add administrative users and/or groups to LucidWorks on the LucidWorks Admin UI Settings page. To enable LDAP in LucidWorks, set the environment variable lweui.ldap.enabled=true in the master.conf file ($LWE_HOME/conf/master.conf).
 | Map a Valid LDAP User/Group to Authorization Before Enabling LDAP Because the built-in authentication is disabled when LDAP authentication is enabled, you cannot 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 Settings 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 standard LDAP integration, the LDAP administrative user only needs permissions to query the LDAP server for users and groups. Lucid Imagination strongly recommends you create an LDAP admin user with only the necessary minimal user and group querying permissions for use with LucidWorks.
LucidWorks also allows you to authenticate users without LDAP administrative credentials. This method is called "queryless" authentication, because LucidWorks does not query the LDAP directory for user information. Rather, LucidWorks uses the attribute value plus the user's login and the base suffix as the user's DN. This method only works if the exact location of your LDAP user data is known and is the same for all relevant users. Another limitation of queryless authentication is that LucidWorks cannot find members of a group, only individual users.
It is also possible, using standard Java SSL functionality, to use certificate authentication with a SSL-enabled LDAP server. More information on that is available here: http://docs.oracle.com/javase/jndi/tutorial/ldap/security/ssl.html.
For information about filtering search results based on LDAP permissions, see Restricting Access to Content and Search Filters.
LDAP Configuration File
The main configuration file for configuring LDAP is $LWE_HOME/conf/ldap.yml. The default settings must be modified as needed for LucidWorks to connect to the LDAP server and query the database for user authentication. After the file has been edited, restart the server.
Here is the default content of the ldap.yml file. Note that the file includes sample configurations for standard LDAP authentication, queryless authentication, and Microsoft ActiveDirectory integration for use with Windows Shares data sources.
######################################################## # Warning: Always restart the application after adjusting # your LDAP config, or unpredictable behavior may result. ######################################################## # production: # host: localhost # port: 389 # 636 for SSL # attribute: uid # base: dc=xyz,dc=corp,dc=com # # user_query: '$ATTR=$LOGIN' # default query is '$ATTR=$LOGIN', set this if you need something more complex # admin_user: cn=Manager,dc=xyz,dc=corp,dc=com # If you don't have an admin password, you can disable # admin_password: secret # admin login in the UI "Settings" page # ssl: false # group_base: ou=groups,dc=xyz,dc=corp,dc=com # group_membership_attribute: uniqueMember # group_name_attribute: cn # # group_query: '(&(objectclass=groupOfUniqueNames)($ATTR=$USER))' # default query is '$ATTR=$USER' where $USER is user's DN # Attribute Definitions # # (see below for sample configs) # attribute: The attribute of the user object that the system will use to search for the user, # or assume when constructing an explicit DN via query-less authentication # base: Search base for user queries, or suffix appended to attribute+login for queryless authentication # user_query: (optional) supplies an arbitrarily complex query if the default user query is not sufficient. # Variable substitutions: # $ATTR will be substituted with the value of 'attribute' from above # $LOGIN will be substituted with the value the user entered in the login form in the UI # search is performed using 'base' as a search base # admin_user: login to use for searching the directory - not used with query-less authentication # admin_password: password to use for searching the directory - not used with query-less authentication # ssl: enable/disable SSL # group_base: Search base for group queries. Not used with query-less authentication # group_membership_attribute: The attribute to look for in the group object that will contain members' user DNs # group_name_attribute: The attribute of the group object that the system will use to search for the group # group_query: (optional) supplies an arbitrarily complex query if the default group query is not sufficient. # Variable substitutions: # $ATTR will be substituted with the value of 'group_name_attribute' from above # $USER will be substituted with the logged-in user's fully-qualified LDAP DN # search is performed using 'group_base' as a search base # Note: The default query ($ATTR=$USER) does not specify the object type for groups # several different group object types are common, e.g. group, groupOfNames, groupOfUniqueNames. # Therefore, non-group objects may also match if they contain an a matching attribute # Sample Configurations # # Basic Configuration: # production: # host: localhost # port: 389 # 636 for SSL # attribute: uid # base: dc=xyz,dc=corp,dc=com # admin_user: cn=Manager,dc=xyz,dc=corp,dc=com # admin_password: secret # ssl: false # group_base: ou=groups,dc=xyz,dc=corp,dc=com # group_membership_attribute: uniqueMember # often this is just 'member' # group_name_attribute: cn # # Basic Queryless Authentication: # Notes: # Disable "Use admin credentials in UI /settings/edit page", and restart # Group lookup is not possible in this mode # production: # host: localhost # port: 389 # 636 for SSL # attribute: uid # base: ou=users,dc=xyz,dc=corp,dc=com # ssl: false # # all other attributes are invalid with queryless authentication # # Microsoft ActiveDirectory # production: # host: localhost # port: 389 # 636 for SSL # attribute: userPrincipalName # AD uses userPrinciapalName for email address, e.g. fred@domain.com # base: dc=domain,dc=com # admin_user: cn=Manager,dc=corp,dc=com # admin_password: secret # ssl: false # group_base: ou=groups,dc=corp,dc=com # group_membership_attribute: member # group_name_attribute: name
The attribute definitions included in the ldap.yml file are as follows:
| Attribute | Definition | ||
|---|---|---|---|
| attribute | The attribute of the user object that the system will use to search for the user, or assume when constructing an explicit DN via query-less authentication. | ||
| base | Search base for user queries, or suffix appended to attribute + login for queryless authentication. | ||
| user_query | Optional: supplies an arbitrarily complex query if the default user query is not sufficient. Variable substitutions are as follows: $ATTR will be substituted with the value of 'attribute' from above; $LOGIN will be substituted with the value the user entered in the login form in the UI. Search is performed using 'base' as a search base. |
||
| admin_user | Administrative login to use for searching the directory. Not used for queryless authentication. | ||
| admin_password | Administrative password to use for searching the directory. Not used for queryless authentication. | ||
| ssl | Enable/disable SSL. | ||
| group_base | Search base for group queries. Not used with queryless authentication. | ||
| group_membership_attribute | The attribute to look for in the group object that will contain members' user DNs. | ||
| group_name_attribute | The attribute of the group object that the system will use to search for the group. | ||
| group_query | Optional: supplies an arbitrarily complex query if the default group query is not sufficient. Variable substitutions are as follows: $ATTR will be substituted with the value of 'group_name_attribute'; $USER will be substituted with the logged-in user's fully-qualified LDAP DN. Search is performed using 'group_base' as a search base.
|
User to Group Mappings
LucidWorks 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.
Manual User Management
LucidWorks also includes a REST API that allows creation and authentication of users. Using this API and the Perl Examples provided with the application, users can be created, passwords reset, and accounts deleted. As mentioned previously, API-based user management and LDAP authentication are mutually exclusive: you can only use one user management method.
