This TestRail script allows you to integrate TestRail with an Active 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 Active Directory integration. To learn more about TestRail authentication scripts, please see the detailed implementation guide.
Please note: even though the authentication can be done through Active Directory, 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 Active Directory fully supports this feature, but you should still be aware of this fact.
Download
You can download the latest version of the Active Directory authentication script here:
Active Directory integration script
A script to integrate TestRail with Active Directory
Requirements
In order to use this script, there are a few requirements that must be met. Because the directory service of Active Directory is queried via the LDAP protocol, TestRail requires the PHP LDAP extension to integrate with Active Directory. 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, then the LDAP extension is already installed together with PHP. You just need to activate it in your PHP.ini file. To so, please just add the following line to the PHP.ini file:
extension=php_ldap.dllDon’t forget to restart IIS to activate the changes.
For some previous PHP and Windows versions, you can select Programs & Features from the Windows Control Panel. Then right-click PHP, select Change, and install the LDAP extension.
Active Directory: 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 Active Directory user to have a valid unique email address. Please add the email addresses to your user objects in Active 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 Active Directory 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 active directory server. Example: ad1.directory.example.com |
AUTH_PORT |
The LDAP port of the directory server. This is usually 389. |
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 domain and organization name or the Users group. Example 1: CN=Users,DC=directory,DC=example,DC=com Example 2: OU=Example Inc,DC=directory,DC=example,DC=com You can also specify specific user groups if you only want to allow specific users to authenticate with TestRail. |
AUTH_DOMAIN |
The domain name used by Windows (this is the name often used as a prefix for user names, such as directory\bob) Example: directory |
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 Active Directory 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 Active Directory. |
AUTH_MEMBERSHIP |
Optionally verifies if a user is member of the specified security group(s). This must be a regular expression that is checked against all memberOf values. If one of the entries matches, the user is authenticated. If none of the memberOf values match, access is denied. Example: /^CN=My Group,/ |
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 > Login. 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.