You can integrate TestRail with external authentication systems such as Active Directory, databases, other applications and APIs to implement single sign-on and to create the initial TestRail user accounts. This article discusses the technical details of the integration and explains how to build your own integration scripts. If you are just looking for details on how to integrate TestRail with Active Directory, please read this article.
Implementation details
To allow TestRail to integrate with almost any external system, TestRail supports authentication scripts. If you install an authentication script, TestRail will ask your script if a user’s credentials are valid when the user tries to login.
How an authentication script verifies the credentials depends on the external authentication system. For example, the script could query a database to verify the username and login. Or it could call a Web API to check the credentials. Regardless of the method used to verify the credentials, the script returns the authentication result to TestRail to either deny or allow a user to login.
Script basics
An authentication script for TestRail is generally written in PHP. If you want to integrate TestRail by using another programming tool or language, this would be possible by simply calling your external tool or even Web API from the authentication script.
The anatomy of a TestRail authentication script is very simple. You basically just need to implement a single authenticate_user function. The username and password is passed to this function by TestRail. After verifying the credentials, the script needs to return the authentication result to TestRail.
// The anatomy of a basic authentication script
function authenticate_user($name, $password)
{
// Verify the credentials and return result
// ..
}Tip: It’s recommended to not close the <?php tag at the end of the file. This ensures that there are no white-spaces at the end of the file that could change PHP’s output behavior.
Returning the result
Once the script has verified the credentials, it needs to return the authentication result back to TestRail. This is done by creating an AuthResult object and passing all relevant arguments. A script can also raise an exception to signal an unrecoverable error, such as a connection error to an external system the script depends on. The following sections explain how to return results to TestRail.
Signaling errors
If any errors occur during the verification of the user’s credentials, it’s recommended to raise an exception. For example, if your script connects to a database to verify the username and password but the database cannot be reached, simply raise an exception with an appropriate error message. It’s recommended to use TestRail’s AuthException exception type for this:
// The anatomy of a basic authentication script
function authenticate_user($name, $password)
{
// Verify the credentials and return result
// ..
}Authentication denied
If your script determines that the authentication failed and the user access is denied, simply create and return an instance of the AuthResultDenied class.
function authenticate_user($name, $password)
{
// [..]
return new AuthResultDenied();
}Authentication success
To authorize a user, simply return an instance of the AuthResultSuccess class. TestRail needs the email address of the user to link the authentication result to TestRail’s internal user accounts.
If you use the email address of the user as the login, then you can simply return the login to TestRail. Otherwise, you need to look up the email address as part of the authentication (for example, by reading the user’s email address from your authentication database or external system).
function authenticate_user($name, $password)
{
// [..]
return new AuthResultSuccess($user_email);
}TestRail also allows you to automatically create new user accounts for users who log in for the first time. This is a great way to automatically create all initial user accounts.
For example, if you want to integrate TestRail with Active Directory, you could ask TestRail to create a user account for users who log in for the first time. You would then simply send a link to your TestRail installation to all users via email and TestRail would transparently create new user accounts. To use this feature, it’s required to also provide TestRail with the full name (first name + last name) of the user.
function authenticate_user($name, $password)
{
// [..]
$result = new AuthResultSuccess($user_email);
$result->create_account = true; // Create an account, if needed
$result->name = $user_name; // 'Bob Smith'
$result->role_id = 3; // Optional: ID of the user's role
$result->group_ids = array(1, 2); // Optional: IDs of the user's groups
$result->is_admin = true; // Optional: Admin privileges
return $result;
}Authentication fallback
There are situations when you can’t or don’t want to authenticate specific users but want to use TestRail’s built-in authentication system. For those cases you can ask TestRail to fall back to its own authentication system. You can of course do this on a case by case basis.
For example, you could allow users to login with their Active Directory credentials as well as their TestRail account at the same time. If the user enters an email address as the username (instead of an Active Directory login), you could ask TestRail to use its own authentication system for this user. To do this, simply return an instance of the AuthResultFallback class.
function authenticate_user($name, $password)
{
// [..]
return new AuthResultFallback();
}Installation
To install an authentication script, simply name it auth.php and place it into your custom/auth/ directory below 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.