This section explains how to use the LDAP Checker tool a script (ldap-checker.jar) that checks and reports on an LDAP configuration. Instructions for use are also provided in the README.txt file that accompanies the tool.

The ldap-checker script is included with the Clarity LIMS installation and is available at the following location:

/opt/gls/clarity/tools/ldap-checker

The ldap-checker script performs numerous checks of the LDAP configuration and reports on any incorrect items found.

Script Properties

Point the script to one or more files containing (at a minimum) the database connection properties. Alternatively, set these properties from the command line.

The script loads properties from the following sources and in the following order:

1. Any JDBC properties files specified with -f (see the table for options).

   If multiple properties files specify the same property, the last file is used.

2. Any Java system properties specified on the command line using

   Copy

   -D<propertyName>=<propertyValue>

   Properties specified on the command line are only checked if they do not appear in the properties files.

3. The properties table in the database.

   The properties table is only checked if the same property is not already specified in the properties file or on the command line.

After the script has the basic database connection properties, it loads further settings from the corresponding Clarity LIMS database.

The following JDBC properties are required:

• jdbc.driverClassName

• jdbc.url

• jdbc.username

• jdbc.password

Options:

Run the Script

1. Change to the directory containing ldap-checker tool:

   Copy

   /opt/gls/clarity/tools/ldap-checker

2. Run the script. To specify a properties file, use the following example:

   Copy

   java -jar ldap-checker-<version>.jar -f database.properties 

Example Properties File

The tool includes an example database.properties file. This example shows a properties file that is specified with the -f option.

The following options are available:

• Edit this file and use it.

• Provide properties on the command line, using: -D.

  For example:

  Copy

  -Djdbc.url=<url to properties file> 

Examples

Example 1: Using SSL

Specify and provide the path to the keystore:

java -Djavax.net.ssl.trustStore=/path/to/keystore -jar ldap-checker-<version>.jar -f database.properties 

Example 2: Checking Users

To check a set of specific users (even those that have not been provisioned), use the following script:

java -jar ldap-checker-<version>.jar -u usertocheck -f database.properties 

Overriding Properties

To override properties that are typically loaded from the properties table, use command-line system properties or one or more properties files.

Using system property ( -D options must be specified before the -jar option):

java -Djavax.net.ssl.trustStore=/path/to/keystore -Dldap.managerPass=mypassword -jar ldap-checker-<version>.jar -u usertocheck -f database.properties

Using multiple properties files:

java -jar ldap-checker-<version>.jar -u usertocheck -f database.properties custom-ldap.properties

• In this example, Custom-ldap.properties might resemble the following:

ldap.managerDn=CN=GLS Admin,CN=Users,DC=gls,DC=lan

ldap.managerPass=mypassword

If you use, or would like to use, an LDAP server to consolidate directory services, it is possible to integrate LDAP with Clarity LIMS.

The Clarity LIMS LDAP solution allows for the following features:

• User name and password authentication against LDAP to govern access to Clarity LIMS.

• Ongoing unidirectional synchronization of user information (such as first name, last name, title, phone, fax, and email) from LDAP to Clarity LIMS. For example, if your telephone number is changed in the LDAP directory, the information is pushed down to Clarity LIMS, keeping contact information current.

• Automated unidirectional provisioning of user accounts from LDAP to Clarity LIMS. For example, adding a user to a particular group within the LDAP directory automatically results in a local account with LDAP authentication being added to Clarity LIMS.

Providing Information about your LDAP Implementation

Our Field Application Specialist (FAS) team meets with you to discuss the current LDAP implementation. In preparation for this meeting, collect the following information:

• The type of provisioning you would like to use to synchronize Clarity LIMS with LDAP (automatic or manual).

• A list of the LDAP attributes the current system uses to record the following user properties: first name, last name, title, phone number, fax number, and e‐mail address.

NOTE: When integrating Clarity LIMS with LDAP, the LIMS database and the LDAP directory remain as separate and distinct entities.

Supported LDAP Servers

Clarity LIMS is tested with the following LDAP servers:

• ApacheDS 1.5 and later

• Microsoft Active Directory (Windows Server 2003 or later)

• OpenLDAP 2.3.35 and later

Access and Changes

While user provisioning and authentication are handled with LDAP, a Clarity LIMS system administrator completes the following steps:

1. Determine the level of access that a user requires.

2. Modify the userʹs account within the LIMS to provide that access.

Once an LDAP integration with Clarity LIMS is established, all changes to user profiles must be made from the LDAP server.

Provisioning Users

Only automatic user provisioning is available.

With automatic user provisioning, Clarity LIMS users are created automatically by a provisioning tool that periodically synchronizes the LDAP server with the LIMS.

To make use of the LDAP directory services, Clarity LIMS maps to specific LDAP attributes within a defined schema.

However, the directory structure used can vary among installations. Our Field Applications Specialist (FAS) team work with you to complete the following items:

• Analyze a specific LDAP solution and directory organization or assist with the selection and initial configuration of an LDAP service.

• Discuss the user elements that will be synchronized between the LDAP service and Clarity LIMS systems.

• Configure LDAP to connect to your Clarity LIMS systems.

Caching User Authentication Results from your LDAP Server

User authentication is handled in the Clarity LIMS.

In previous versions of Clarity LIMS, a few customers reported slow response time for the REST API when using LDAP users for authentication. As of Clarity LIMS v5.2.x / v4.3.x, the REST API response time has improved by introducing a new feature that caches user authentication results through a new property (api.session.timeout).

To make use of the new feature, do the following actions:

• Make sure that api.session.timeout property is set.

• Include the HTTP Connection & Authorization request headers and session cookie in the HTTP request.

Setting the api.session.Timeout Property

Stored in the Clarity LIMS database table, the api.session.timeout property allows you to specify the period of time for which a user's session should persist, after they have been authenticated.

This property is set during installation or upgrade of the LIMS. The default value is 5 minutes. If necessary, update the value using the omxprops-ConfigTool.jar tool at the following location:

/opt/gls/clarity/tools/propertytool

For example:

$ java -jar /opt/gls/clarity/tools/propertytool/omxprops-ConfigTool.jar
set -y api.session.timeout '15'

For this configuration to take effect, stop and restart Tomcat:

service clarity_tomcat stop
service clarity_tomcat start

Including the HTTP Authorization Request Header and Session Cookie

To persist user authentication, the HTTP request must contain the following HTTP request headers:

• Request Header

  • Connection: Keep-Alive

  • Authorization: Basic <credentials>

The HTTP request headers are required for the initial request, and for any subsequent request to get a valid JSESSIONID. Additional scenarios are described in the following table.

To make sure that a valid authenticated session is provided if the cookie in the request has expired, also provide the following JSESSIONID cookie:

• Cookie

  • JSESSIONID=<a valid JSESSIONID from the initial request>

The following table lists the various combinations of HTTP Authorization request header and JSESSIONID cookie and their expected result. It assumes that the HTTP Connection request header is provided for all scenarios.