This TestRail script allows you to integrate TestRail with an LDAP directory service to implement single sign-on and to create the initial TestRail user accounts. The following sections explain how to install, configure and customize the LDAP integration. To learn more about TestRail authentication scripts, please see the detailed implementation guide.
Integrating with Microsoft Active Directory? If so, please use our special Active Directory integration script instead.
Please note: even though the authentication can be done through LDAP, each user still needs a valid TestRail user account. TestRail user accounts are still needed for TestRail specific user settings and other reasons. TestRail’s authentication module allows scripts to transparently create user accounts if needed and this authentication script for LDAP fully supports this feature, but you should still be aware of this fact.
Download
You can download the latest version of the LDAP authentication script here:
LDAP integration script
A script to integrate TestRail with LDAP servers
Requirements
In order to use this script, there are a few requirements that must be met. As we are using the LDAP protocol, TestRail requires the PHP LDAP extension to be installed. If you are hosting TestRail under Linux, you can usually install the LDAP package with your package manager. E.g. Ubuntu:
$ sudo apt-get install php7.2-ldapIf you are using Windows Server to host TestRail, you will need to install the LDAP extension manually. You can either get the required php_ldap.dll file from PHP.net (you likely want the files for PHP 7.x, VC9 x86 Non Thread Safe). Don’t forget to add the extension to the PHP.ini after placing it in PHP’s ext directory and to restart IIS.
Or if you installed PHP via Microsoft’s Web Platform Installer, you can also select Programs & Features from the Windows Control Panel. Then right-click PHP, select Change, and install the LDAP extension.
Because TestRail uses the user’s email address as the unique account ID, TestRail needs the email address of users for the authentication. This script expects the email address field of the LDAP user to have a valid unique email address. Please add the email addresses to your user objects in your LDAP directory in case you don’t have this already. You could alternatively modify this script to automatically generate the email address based on the login name.
Configuration
Before you install the script (please see the next section for the installation instructions), you need to configure the script with your LDAP settings. To configure the script, simply open the script in a text editor and change the settings at the beginning of the file. The constants are explained in the following table.
| Constant | Description |
|---|---|
AUTH_HOST |
The fully qualified domain name of the LDAP directory server. Example: ldap://ldap.example.com |
AUTH_PORT |
The LDAP port of the directory server. This is usually 389. |
AUTH_BIND_DN |
The LDAP distinguished name of the user account used to query a user object from the directory. |
AUTH_BIND_PASSWORD |
The password of the user account used to query a user object from the directory. If both settings, AUTH_BIND_DN as well as AUTH_BIND_PASSWORD, are left blank, TestRail will try to use anonymous authentication. |
AUTH_DN |
The base LDAP distinguished name to find and authenticate users against. This must include at least the top OU, CN and/or DC entries. This usually includes the organization name and an organizational unit (OU). Example 1: OU=people,DC=example,DC=com |
AUTH_FILTER |
The filter expression that is used to find and retrieve the directory object of the user who is authenticated. The expression has to follow the common LDAP filter syntax.
When performing the search, the placeholder %name% will be replaced with the username that was entered on TestRail’s login page. Example: (&(uid=%name%)(objectClass=posixAccount)) |
AUTH_CREATE_ACCOUNT |
This configuration setting specifies if TestRail should automatically create new user accounts in TestRail if a user could be successfully authenticated. This is a great way to create all the necessary user accounts in your organization without creating TestRail accounts manually. Simply set this option to true and send all users an email with TestRail’s web address. The accounts for users will automatically be created when they first login. |
AUTH_FALLBACK |
Allow users to continue login with their TestRail credentials in addition to the LDAP login. If enabled, TestRail tries to authenticate the user with her TestRail credentials if an email address is entered. If a username is entered, TestRail authenticates the user against LDAP. |
AUTH_NAME_ATTRIBUTE |
The name of the attribute that stores the user’s full name. This attribute is used when a new TestRail user account is created. |
AUTH_MAIL_ATTRIBUTE |
The name of the attribute that stores the user’s email address. This attribute is used to link LDAP user records to TestRail user accounts. |
Installation
To install this script, simply place it into your custom/auth/ directory of your TestRail installation. Once the script has been added to TestRail, it will be used to authenticate users. You can also see the exact path and status of the authentication script in TestRail under Administration > Site Settings > Auth.
To deactivate the script, simply remove or rename the auth.php file. Users will then be able to login with their email address and TestRail passwords.