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:
Attribute Name | Attribute Value |
FirstName | user.firstName |
LastName | user.lastName |
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