Integrating LDAP with Oracle Commerce Workbench

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:

  1. 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.

  2. If no manually configured user exists for the name entered, Workbench attempts to authenticate the user against the LDAP directory.

  3. If the user is configured for LDAP authentication in Workbench, any associated permissions are applied.

  4. 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:

  1. Stop the Endeca Tools Service.

  2. Navigate to %ENDECA_TOOLS_CONF%\conf (on Windows) or $ENDECA_TOOLS_CONF/conf (on UNIX).

  3. Open the webstudio.properties file, and locate the com.endeca.webstudio.useLdap property: 

    # LDAP Authentication
com.endeca.webstudio.useLdap=false

  4. Change the value of the property to true: 

    com.endeca.webstudio.useLdap=true

  5. Save and close the file.

  6. Open the Login.conf file.

    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.

  7. Uncomment and modify the login profile according to your LDAP configuration.

    For details about profile parameters, see Syntax of LDAP login profile configuration parameters.

  8. Save and close the file.

  9. Start the Endeca Tools Service.

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

%{#username}

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.

%{#groupname}

The name of the LDAP group as entered in the User Settings tool in Workbench.

%{#dn}

The distinguished name of the user or group object in the LDAP directory.

%{#dn:n}

The value of the path field at index n in the distinguished name of the user or group object in LDAP.

For example, if the value in the %{#dn} field is cn=joe,ou=People,dc=foo,dc=com, then the value “People” will be substituted for %{#dn:1}, while “joe” will be substituted for %{#dn:0}. Note that unlike the value of %{#dn}, which is the raw value returned from the LDAP server, the values returned by this template are not LDAP escaped.

%{#fieldname}

The value in the specified field of the user object (or group object when used in the groupTemplate or findGroupTemplate parameter) under consideration.

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:

Parameter

Description

authentication

Specifies the method of authentication that should be used in binding to the LDAP server as a user account. The permitted values are none, simple, or EXTERNAL

checkPasswords

Not supported in Workbench 3.1.1 Optional. Determines whether Workbench checks passwords during logins. Default value is true. If set to false, Workbench uses only the user name to authenticate from the LDAP directory.

credentialsKey

Key name with which serviceUsername and servicePassword are pushed into OCS:

LDAP credentials (servicePassword and serviceUsername) must be stored in the instance of the OCS defined by jps-config at the default path location.

Note: You must also provide values for the following parameters in order to connect to the LDAP server:

findGroupPath

The query that is passed to the LDAP server to find a specific group. You can use the %{#groupname} template to insert the name of the group as entered in the User Settings tool into the query. Be sure to set the appropriate objectClass.

For example: 

findGroupPath="/ou=groups,dc=example,dc=com¬
??sub?(&(objectClass=group)(cn=%{#groupname}))"

findGroupTemplate

A template that specifies how to produce the group name from the group object returned by the findGroupPath query. Like the userTemplate, this template is used to correct the case of a group name when you add LDAP group profiles in Workbench. Therefore, the value returned by this template should match the name entered in the User Settings tool, except for possible differences in case.

groupPath

The query that is passed to the LDAP server to find all the groups of which a user is a member. This query is executed when a user logs in to Workbench after looking up the user with the userPath query. Thus, you can use templates to insert any information from the user object that is returned by the previous query, such as the distinguished name of the user or any other LDAP attributes, into the groupPath query. You can specify multiple values for groupPath.

groupTemplate

A template that specifies how to produce individual group names from the set of groups returned by the groupPath query. The value returned by this template should match the name of the LDAP group as defined in the Workbench user profile. You can specify multiple values for groupTemplate.

keyStoreLocation

Used only if useSSL=true. The location of the Java keystore, which stores keys and certificates. The keystore is where Java gets the certificates to be presented for authentication. The location of the keystore is OS-dependant, but is often stored in a file named .keystore in the user’s home directory.

Note

Even if this location is on a Windows system, the path uses forward slashes, (/) not backslashes (\).

keyStorePassKey

Key name with which keyStorePassPhrase is pushed into OCS. Used only if useSSL=true.

keyStorePassKey must be stored in the instance of the OCS defined by jps-config at the default path location.

keyStorePassphrase

The passphrase used to open the keystore file. Used only if useSSL=true.

ldapBindAuthentication

Not supported in Workbench 3.1.1 Optional. By default this is set to true, and Workbench authenticates users by rebinding as the user to the LDAP system, thereby employing the LDAP system’s own authentication mechanism.

loginName

Optional. A template login name that will be used to bind to the LDAP server. Default value is %{dn}.

passwordAttribute

Not supported in Workbench 3.1.1 Optional. The name of the attribute on the user object that contains the user’s password. Used only if ldapBindAuthentication is set to false. The field specified must contain the user’s password in clear text. By default this is set to userPassword.

serverInfo

See credentialsKey above.

serviceAuthentication

See credentialsKey above.

servicePassword

See credentialsKey above.

serviceUsername

See credentialsKey above.

userPath

The query that is passed to the LDAP server to find an individual user. You can use the %{#username} template to insert the name entered in the User Settings tool or the name entered in the Workbench login page into the query. Be sure to set the appropriate objectClass.

For example: 

userPath="/ou=users,dc=example,dc=com??sub?¬
(&(objectClass=person)(uid=%{#username}))"

userTemplate

A template that specifies how to produce the username from the user object returned by the userPath query.

This template allows Workbench to automatically correct the case (capital or lowercase) of the username to match the name exactly as specified in the LDAP directory. The correction occurs when you add an LDAP user to Workbench. Therefore, the value returned by this template should match the name entered in the User Settings tool, except for possible differences in case.

useSSL

Optional. Default value is false. If set to true, Workbench attempts to make mutually authenticated SSL connections to the LDAP server. If you set the parameter, ensure that you have configured the LDAP server to use SSL and that the value of serverInfo has the protocol specified as ldaps:// with an SSL port.

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

firstNameTemplate

A template that specifies how to produce the user’s first name from the user object, for example, %{#firstNameAttribute}.

lastNameTemplate

A template that specifies how to produce the user’s last name from the user object, for example, %{#lastNameAttribute}.

emailTemplate

A template that specifies how to produce the user’s email address from the user object, for example, %{#emailAttribute}, or %{usernameField}@companydomain.com.

findGroupEmailTemplate

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:

  1. Navigate to %ENDECA_TOOLS_ROOT%\server\bin (on Windows) or $ENDECA_TOOLS_ROOT/server/bin (on UNIX).

  2. Open the setenv.bat or setenv.sh file.

  3. 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

  4. 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:

  1. Open the Registry Editor.

  2. Navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\ Procrun 2.0\EndecaToolsService\Parameters\Java\Options key.

  3. Right click Options in the right pane and select Modify.

    The Edit Multi-String dialog box displays.

  4. Locate the following parameter: 

    -Djava.security.auth.login.config=%ENDECA_TOOLS_CONF%/conf/Login.conf

  5. Change the path to point to the location of your configuration file.

  6. Click OK.

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.

Copyright © Legal Notices