Configure Single Sign-On (SSO)

TestRail’s SSO feature allows administrators to integrate TestRail with their preferred SSO identity provider (IDP) using the SAML 2.0 protocol. In practice, this means that the management of users can be streamlined, by creating them once in the IDP and then providing them with access to whichever applications are required by the user – TestRail, in this case.

Once configured, TestRail SSO will automatically authenticate new users that have been authorized to use TestRail in the IDP. This means that testers can login once, and get on with their work, and administrators no longer need to concern themselves with the day to day management of users in TestRail.

With SSO configured, you have some additional options for managing your users:

• Continue to create users in TestRail but force them to login via integrated SSO Identity Provider.
• Manage users in your SSO identity provider and have TestRail automatically create users if they are successfully authenticated, forcing them to login using their SSO identity.
• Allow users to continue using their TestRail login credentials, in addition to their SSO identity.

You can enable SSO by navigating to Administration > Site Settings > SSO, switching the SSO Configuration Off/On toggle to on, and filling out the required settings. You can use the SSO configuration page to integrate with any identity provider that supports SAML 2.0 identity authentication.

Example configurations are provided for Okta and Azure below.

Configuring SSO in Okta

• In Okta, login as an administrator and navigate to the Admin > Applications area 
• Click the Add Application button
• Click the Create New App button, select SAML 2.0 then confirm by clicking the Create button
• Give the app a name – e.g. TestRail and upload a logo if you desire
• Click the Next button
• Login to TestRail & navigate to the SSO page in the Administration > Settings console
• Copy the Entity ID from the TestRail SSO configuration page and paste it into the Okta Audience URI (SP Entity ID) field
• Copy the Single Sign On URL from the TestRail SSO configuration page and paste it into the Okta Single sign on URL field
• Leave the Use this for Recipient URL and Destination URL checkbox checked in Okta
• The Name ID format and Application Username fields can be ignored
• Set the Attribute Statements in Okta to the following:

• Click the Next button in Okta and fill out the questionnaire or other remaining fields as required
• Once done, or on the Sign On tab in Okta, click the View Setup Instructions button to display the required URLs and certificate for TestRail

• Copy and paste the Identity Provider Single Sign-On URL and Identity Provider Issuer URL from Okta and paste them into the TestRail IDP SSO URL & IDP Issuer URL fields respectively
• Copy and paste (or download then upload) the X.509 Certificate from Okta into TestRail
• Click Save. Test your connection to verify the settings
• So long as the administrator you’re using to configure the settings in TestRail is assigned to the app you created in Okta, the connection test should succeed and you’re now ready to use TestRail in Single Sign-On (SSO) mode.

**Configuring SSO in Azure

Steps for configuring Azure are similar to those used for Okta, but with some differences.

First, configure the following items in the Azure SSO console:

• Identifier = TestRail Entity ID
• Reply URL = TestRail Entity ID
• Sign on URL = TestRail Single Sign On URL

Use the attributes below:

*In some instances, this will be user.userprincipalname

Next, download the “Certificate (Base64)”. Configure the following items in TestRail.

• For the IDP SSO URL, use the Azure SAML SSO Login URL
• For the IDP Issuer URL, use the Azure AD Identifier URL
• For the IDP Certificate, upload the certificate from Step 3 into TestRail, as shown in the image below.

Create Users in SSO and Force SSO Authentication

Pre-requisites:

• Matching user account exists in SSO IDP and App is assigned to the account
• SSO is configured in TestRail with Authentication Fallback disabled

You can create users automatically in TestRail once they have been created in the SSO IDP by following the steps below:

1. Create a user in the SSO IDP
2. Navigate to the TestRail login and click the Single Sign-On button
3. Fill out the SSO login form (if not already logged in) as the user from 1
4. Once the SSO login is completed, you will be redirected to the TestRail dashboard as the user from step 1

Manage Users in SSO IDP and Create Automatically in TestRail

Pre-requisites:

• User account exists in SSO IDP and App is assigned to the account
• SSO is configured in TestRail with the Create an account on first login checkbox enabled

You can create users automatically in TestRail once they have been created in the SSO IDP by following the steps below:

1. Create a user in the SSO IDP
2. Navigate to the TestRail login and click the Single Sign-On button
3. Fill out the SSO login form (if not already logged in) as the user from 1
4. Once the SSO login is completed, you will be redirected to the TestRail dashboard as the user from step 1

Allow Users to Continue Using their TestRail Login Credentials in Addition to SSO

Pre-requisites:

• User account exists in SSO IDP and App is assigned to the account
• SSO is configured in TestRail with the Create an account on first login checkbox enabled

Authentication Fallback checkbox is enabled

1. TestRail users can continue to login using their existing TestRail credentials if the authentication fallback SSO checkbox is checked:
2. Create a user in the SSO IDP
3. Navigate to the TestRail login and click the Single Sign-On button
4. Fill out the SSO login form (if not already logged in) as the user from 1
5. Once the SSO login is completed, you will be redirected to the TestRail dashboard as user from 1
6. Navigate to My Settings in TestRail and set a password for the user account
7. Logout
8. Enter email and password in appropriate fields on the TestRail login screen & click Log In
9. User is logged in successfully (using standard TestRail authentication) & TestRail dashboard page is displayed