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.

Single Sign On is a TestRail Enterprise feature. Please contact us to upgrade your license to the Enterprise product tier to access this functionality.

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:

Attribute Name	Attribute Value
FirstName	user.firstName
LastName	user.lastName
Email	user.email

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

Important: Within your Azure Portal, you will need to enable SAML ToolKit.
Please ensure that your steps are properly completed from this guide before proceeding.

TestRail – SSO URLs
1. Login to TestRail as an administrator
2. Go to Administration -> Site Settings -> SSO
3. Click the “SSO Configuration Off/On” radio button
4. Under “Entity ID”, copy this URL for later use
5. Under “Single Sign On URL”, copy this URL for later use
6. Select Cancel as no further configuration is required yet
7. Proceed with the next section of instructions

Azure – SAML Configuration
8. Login to your Azure Portal and access your Azure AD SAML Toolkit application
9. On the left hand side, under the Manage section, select “Users and Groups” and add your preferred user(s).
10. Navigate to “Single sign-on” and select SAML
11. Save the “Login URL” (SSO) copy this URL for later use
12. Save the “Azure AD Identifier” (Entity) copy this URL for later use
13. Download the Certificate (Base64), open using a text editor/notepad and save this for later use
14. Under “Basic SAML Configuration” click “Edit”
15. Under “Identifier (Entity ID)”, provide the “Entity ID” metadata URL from step 4
16. Under “Reply URL (Assertion Consumer Service URL)”, provide the “Entity ID” metadata URL from step 4
17. Under “Sign on URL”, provide the “Single Sign on URL” from step 5 and save
18. There is no need to re-configure mappings, leave the default options as is
19. Navigate to Self Service section
20. Enable “Allow users to request access to this application?”
21. Grant permissions to the desired group

TestRail – Configuring SSO
22. Login to TestRail as an administrator
23. Go to Administration -> Site Settings -> SSO
24. Click the “SSO Configuration Off/On” radio button
25. Under “IDP SSO URL” input the URL provided by Azure from step 11
26. Under “IDP Issuer URL” input the URL provided by Azure from step 12
27. Under “IDP Certificate” input the certificate text provided by Azure from step 13
28. Enable Authentication Fallback or “Create Account on First Login” if preferred
29. Select “Save Settings”

Configuring SSO in Google

TestRail – SSO URLs
1. Login to TestRail as an administrator
2. Go to Administration -> Site Settings -> SSO
3. Click the “SSO Configuration Off/On” radio button
4. Under “Entity ID”, copy this URL for later use
5. Under “Single Sign On URL”, copy this URL for later use
6. Select Cancel as no further configuration is required yet
7. Proceed with the next section of instructions

Google – Creating Custom SAML App
8. Access your Google Admin Console
9. Under the Dashboard, click on Apps and select “SAML apps”
10. Click “Add a service/App to your domain” and select the “Setup my own custom app” option
12. Save the “SSO URL” copy this URL for later use
13. Save the “Entity ID” copy this URL for later use
14. Download the Certificate, open using a text editor/notepad and save this for later use
15. Click Next, name your Application “TestRail” and click Next again
16. Under “ACS URL”, provide the “Single Sign on URL” from step 5
17. Under “Entity ID”, provide the “Entity ID” metadata URL from step 4
18. Leave all the default options alone and select Next
19. Click “Add New Mapping” three times and set the following values:

Application Attribute	Category	User Field
user.givenname	Basic Information	First Name
user.surname	Basic Information	Last Name
user.mail	Basic Information	Primary Email

20. If your settings look like our screenshot, proceed with selecting Finish
21. Access your SAML Apps and TestRail app will be there
22. Click the three dots on the right-hand side and select “ON for everyone” or “ON for some”

TestRail – Configuring SSO
23. Login to TestRail as an administrator
24. Go to Administration -> Site Settings -> SSO
25. Click the “SSO Configuration Off/On” radio button
26. Under “IDP SSO URL” input the URL provided by Google from Step 12
27. Under “IDP Issuer URL” input the URL provided by Google from Step 13
28. Under “IDP Certificate” input the certificate text provided by Google from Step 14
29. Enable Authentication Fallback or “Create Account on First Login” if preferred
30. Select “Save Settings”

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:

Create a user in the SSO IDP
Navigate to the TestRail login and click the Single Sign-On button
Fill out the SSO login form (if not already logged in) as the user from 1
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:

Create a user in the SSO IDP
Navigate to the TestRail login and click the Single Sign-On button
Fill out the SSO login form (if not already logged in) as the user from 1
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

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