This section describes how to configure Workbench to use LDAP for user authentication.
LDAP integration allows you to share user identity information and passwords defined in LDAP with Workbench. You can also assign permissions for LDAP users or across an entire LDAP group rather than configuring Workbench users individually.
By configuring Workbench to use LDAP for user authentication, you enable administrators to create Workbench user profiles that are associated with users in an LDAP directory.
Workbench does not write data to the LDAP directory. Passwords and identity information, such as names and e-mail addresses, are maintained in the LDAP directory. Permissions assigned to an LDAP user or group profile in Workbench are stored in the Endeca Configuration Repository.
LDAP user and group profiles can be used in combination with non-LDAP Workbench user and groups that are manually configured by an administrator. Users can authenticate using either method on the same instance of Workbench.
Optionally, you can enable SSL for communication between Workbench and your LDAP server.
Workbench supports integration with all LDAP servers that comply with LDAP version 3.
After you integrate LDAP with your Workbench installation, you can authenticate users either through LDAP or by configuring them manually in Workbench.
Workbench does the following when a user attempts to log in:
Workbench checks whether the user name matches the name of any manually configured Workbench user in the current application. If such a user exists, Workbench attempts to authenticate the user against the password stored for that user.
If no manually configured user exists for the name entered, Workbench attempts to authenticate the user against the LDAP directory.
If the user is configured for LDAP authentication in Workbench, any associated permissions are applied.
If the individual user is not configured for LDAP authentication in Workbench, Workbench checks the LDAP directory for any groups of which the user is a member.
If a profile exists in Workbench for any of these groups, the user is automatically made a member of each matching group. They inherit the permission of these groups. For more information about inheritance of LDAP group permissions, see “Permissions for LDAP users and groups.”
The User Management tool in Workbench allows you to assign permissions to an LDAP user or group.
A user that exists in the LDAP directory but is not associated with a Workbench user profile, either individually or as a member of an LDAP group, cannot log in to Workbench.
A user who authenticates through LDAP is assigned the union of all permissions associated with all groups of which that user is a member. A user who is a member of multiple LDAP groups defined in Workbench is assigned the broadest permission associated with any of the LDAP groups to which that user belongs. Every time users log in to Workbench, their group membership is synchronized with LDAP so that their permissions are current with any group membership changes.
If you create an LDAP user profile in Workbench for an individual who is also a member of one or more LDAP groups defined in Workbench, that user is assigned any permissions that you specify in the User Management tool in addition to any permissions that the user inherits from membership in LDAP groups. If you specify permissions for an LDAP user who is also a member of an LDAP group, then the user is assigned either the permission specified in the User Management tool or the broadest permission associated with any of the user’s LDAP groups, whichever is broader.
With LDAP enabled, you can create user profiles for both LDAP users and LDAP groups that grant administrator privileges in Workbench.
Note
For administrators, the same precedence rules apply when logging in to Workbench as for non-administrators, so that if a manually configured user profile exists in Workbench, a user cannot to log in through LDAP with the same user name.
Administrators can delete other administrators, but they cannot delete the predefined admin user or the Administrators group. This restriction ensures that changing LDAP permissions or disabling LDAP authentication for Workbench does not disable all administrator logins.
LDAP authentication in Workbench is disabled by default.
Because LDAP configuration is unique to each LDAP server and directory, enabling LDAP authentication in Workbench is a manual process.
To enable LDAP authentication in Workbench:
Navigate to
%ENDECA_TOOLS_CONF%\conf
(on Windows) or$ENDECA_TOOLS_CONF/conf
(on UNIX).Open the
webstudio.properties
file, and locate thecom.endeca.webstudio.useLdap
property:# LDAP Authentication com.endeca.webstudio.useLdap=false
Change the value of the property to
true
:com.endeca.webstudio.useLdap=true
This file contains a sample configuration for LDAP authentication.
Note
By default, Workbench uses the authentication profile in this location. You can specify an alternate configuration file. For more information, see Specifying the location of the LDAP login configuration file.
Uncomment and modify the login profile according to your LDAP configuration.
For details about profile parameters, see Syntax of LDAP login profile configuration parameters.
If you disable LDAP authentication in Workbench by setting the
property
com.endeca.webstudio.useLdap=false
in the
webstudio.properties
file, the options to create a
user profile for an LDAP user or an LDAP group do not display in Workbench.
All new user profiles you create must be manually configured in Workbench. Any users who were configured as LDAP users or as members of an LDAP group lose access to Workbench. Existing user profiles for LDAP users or LDAP groups remain in Workbench in an inactive state, and can be edited by an administrator.
Workbench uses the Java Authentication and Authorization Service (JAAS) to authenticate users against an LDAP directory.
Workbench stores LDAP login configuration
information in the
%ENDECA_TOOLS_CONF%\conf\Login.conf
file. A sample
profile is included in this location by default, but you should modify its
parameters as needed for your LDAP configuration. You can also specify an
alternate location for the configuration file.
If you want to configure JAAS authentication for other applications
running in the Endeca Tools Service (for example, your own Endeca application
or Workbench extensions), you can create additional profiles with unique names
in the
Login.conf
file.
Workbench allows templates to be supplied for certain configuration parameters in the LDAP login profile.
These
templates, indicated by
%{}
escapes, allow values from the authentication
operation (such as a user or group name entered in Workbench or specific values
from the user or group objects in LDAP) to be substituted into the parameter
value. Templates also enable you to extract information from the LDAP user or
group object (such as the exact user or group name as specified in the LDAP
directory) or identity information that is stored in LDAP. The
%{}
escapes are expanded as follows:
Escape |
Description |
---|---|
|
The name of the LDAP user as entered in the User Settings tool in Workbench, or the user name entered by a user at the Workbench login page. |
|
The name of the LDAP group as entered in the User Settings tool in Workbench. |
|
The distinguished name of the user or group object in the LDAP directory. |
|
The value of the path field at index
For example, if the value in the
|
|
The value in the specified field of the user object (or
group object when used in the
|
You specify the values of configuration parameters for LDAP authentication as quoted strings.
If there are any quotation marks (") or backslashes (\) in the string, they must be escaped. For example, if you have the following string:
"A string with an "embedded quote" and a \backslash"
In the profile, it should be specified as follows:
"A string with an \"embedded quote\" and a \\backslash"
For most parameter values, single quotation marks (') do not need to be
escaped and the values you specify for the parameters can include non-ASCII
UTF-8 characters. For additional restrictions on the
userPath
,
groupPath
, and
findGroupPath
parameters, see “LDAP path parameters."
For a full list of the parameters that can be specified in the profile, see the section "Configuration parameters for the LDAP login profile."
This section provides a reference of parameters that can be specified in the LDAP login profile.
The following is a full list of the parameters that can be specified in the profile:
The LDAP configuration profile allows you to specify templates to extract identity information from LDAP user or group objects.
Workbench does not store any identity information such as first name, last name, or email address for LDAP users or groups. Instead, Workbench looks up this information in the LDAP directory when needed. The LDAP configuration profile allows you to specify templates to extract identity information from LDAP user or group objects, but they are not required for authentication via LDAP.
Workbench looks up the identity information for a user or group when
you use the
Check Name
function on the
Add User page to confirm that you are adding the
correct LDAP user or group. If you do not specify templates for retrieving
identity information, the fields are not filled in when you use
Check Name
.
Parameter |
Description |
---|---|
|
A template that specifies how to produce the user’s first name
from the user object, for example,
|
|
A template that specifies how to produce the user’s last name
from the user object, for example,
|
|
A template that specifies how to produce the user’s email
address from the user object, for example,
|
|
A template that specifies how to produce the email address associated with a group in LDAP from the group object. |
The
userPath
,
groupPath
, and
findGroupPath
parameters, when appended to the URL in the
serverInfo
parameter, must conform to RFC 2255.
This
means that certain characters must be encoded in order for the path parameters
to form a valid LDAP URL when appended to the value of the
serverInfo
parameter. Both LDAP and URL encoding may
apply to these strings depending on your data. If possible, verify the URL by
passing it to your LDAP server before specifying it in the configuration for
Workbench.
LDAP encoding affects reserved characters such as the comma (,), equals sign (=), and question mark (?). These characters must be escaped by prepending a backslash (\) when they are not used for their reserved purpose, for example if they appear within a common name or organizational unit.
URL encoding affects characters that are invalid for URLs, such as non-ASCII characters and any unsafe characters as defined in RFC 1738. This includes reserved LDAP characters when they are not used for their reserved purpose. These characters must be replaced with the % sign followed by the appropriate hex code.
For example, if you have the following string as part of your userPath:
ou=Endeca Technologies, Inc.
Applying LDAP encoding produces the following result:
ou=Endeca Technologies\, Inc.
Applying URL encoding to the LDAP-encoded string produces:
ou=Endeca%20Technologies%5C%2C%20Inc.
Any non-ASCII characters or any other characters that are not valid in an LDAP URL must also be properly encoded in the string that you specify in the LDAP login profile.
You can specify multiple LDAP servers and multiple values for the
groupPath
element.
If you specify multiple LDAP servers, the servers are assumed to be equivalent. The choice of which LDAP server to contact is made randomly. If an LDAP server cannot be reached, the LoginModule plug-in proceeds through the remaining servers in order of configuration, wrapping if necessary. For example, if five servers are configured and Server 3 is the first to be contacted, the remaining order of contact is Server 4, Server 5, Server 1, and finally Server 2.
You can specify multiple LDAP servers with multiple instances of the
serverInfo
parameter, by using the format:
serverInfo.n = ”ldap://server_url:port_number”
For example:
serverInfo.0="ldaps://globalcatalog.corp.example.com:3269" serverInfo.1="ldap://globalcatalog.us.example.com:3009"
You can also specify multiple values for the
groupPath
attribute by using the same format, for
example:
groupPath.0="/ou=groups,dc=example,dc=com??sub?(member=%{#dn})" groupPath.1="/dc=example,dc=com?memberOf?sub?(AccountName=%{#username})" groupPath.2="/dc=example,dc=com?memberOf?sub?(CN=%{#dn})"
If you specify more than one
groupPath
, Workbench sends all the queries to the LDAP
server to discover the groups of which a user is a member.
You can specify corresponding values for
groupTemplate
for each
groupPath
. In this case, the value for
groupTemplate.0
is applied to the results of the
groupPath.0
query,
groupTemplate.1
is applied to the results of
groupPath.1
, and so on.
For example:
groupTemplate.0="%{#dn:0}" groupTemplate.1="%{#memberOf:0}" groupTemplate.2="%{#memberOf:0}"
By default, Workbench uses
%ENDECA_TOOLS_CONF%\conf\Login.conf
(on Windows) or
$ENDECA_TOOLS_CONF/conf/Login.conf
(on UNIX) as the LDAP
login configuration file.
If you are running the Endeca Tools Service as a Windows service, see Specifying the location of the LDAP login configuration file using Windows Services
You can substitute any configuration file that includes a LDAP login
profile named
Webstudio
. The file does not have to be named
Login.conf
, but it must be saved in UTF-8 format.
If you want to store the configuration file in a different location, you can pass this location to the Java JVM. How you specify the location depends on how you run the Endeca Tools Service.
If you are running the Endeca Tools Service on Windows from the command line or on UNIX:
Navigate to
%ENDECA_TOOLS_ROOT%\server\bin
(on Windows) or$ENDECA_TOOLS_ROOT/server/bin
(on UNIX).Locate the line that sets
JAVA_OPTS
:set JAVA_OPTS=-Xmx1024m -XX:MaxPermSize=128m -Djava.security.auth.login.config=%ENDECA_TOOLS_CONF%/conf/Login.conf
Change the
-Djava.security.auth.login.config
parameter to point to the location of your configuration file on the file system.
By default, Workbench uses
%ENDECA_TOOLS_CONF%\conf\Login.conf
(on Windows) or
$ENDECA_TOOLS_CONF/conf/Login.conf
(on UNIX) as the LDAP
login configuration file.
If you are running the Endeca Tools Service on UNIX or on Windows from a command line, see "Specifying the location of the LDAP login configuration file."
You can substitute any configuration file that includes a LDAP login
profile named
Webstudio
. The file does not have to be named
Login.conf
, but it must be saved in UTF-8 format.
If you want to store the configuration file in a different location, you can pass this location to the Java JVM. How you specify the location depends on how you run the Endeca Tools Service.
If you are running the Endeca Tools Service on Windows from the command line or on UNIX:
Navigate to the
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\ Procrun 2.0\EndecaToolsService\Parameters\Java\Options
key.Right click Options in the right pane and select Modify.
The Edit Multi-String dialog box displays.
Locate the following parameter:
-Djava.security.auth.login.config=%ENDECA_TOOLS_CONF%/conf/Login.conf
Change the path to point to the location of your configuration file.
If a user cannot log in to Workbench, one of several error messages appears.
If the user is entering the correct LDAP user name and password, there may be a manually configured Workbench user in the same application with the same user name or a Workbench administrator with the same user name.
A user with a manually configured profile always takes precedence over a user authenticating through LDAP.
This error appears when any error occurs other than a user
name-password mismatch or an absence of permissions. It can indicate anything
from a connectivity issue with the LDAP server to a mistake in the
configuration in the LDAP login configuration file located in
%ENDECA_TOOLS_CONF%\conf\Login.conf
. For more
information about the login profile, see “Configuration parameters for the LDAP
login profile.”
Check the Workbench log, located in
%ENDECA_TOOLS_CONF%\logs\webstudio.#.log
for more
information about the causes of authentication failures. In most cases, the
solution is to adjust the LDAP query strings to return the desired results. If
possible, test the query URLs against your LDAP server using an independent
tool in order to confirm that they behave as expected and that each query for a
user or group that exists in the directory returns a unique user or group
object.