1. TestRail Support Center
  2. User Guide
  3. Enterprise guide
  4. Configure single sign-on (SSO)

Azure SSO configuration

Updated

TestRail lets you integrate with your preferred SSO identity provider (IDP) using SAML 2.0, OAuth 2.0, and OpenID Connect protocols. Once you enable the SSO configuration, you can choose your preferred protocol.
This guide specifically helps you with the Azure protocol configuration. Follow these instructions first for the Azure AD web application registration, to register for the App in the portal:

  1. Sign in to the Azure portal, with Admin credentials.
  2. Select Azure Active Directory.
  3. Under the Manage tab in the left sidebar, select App registrations. (Sample Image below)
  4. Click New Registration:

  5. In New Registration: 
    1. Name* – Add name
    2. Supported account types – Select Appropriate Account types
    3. Redirect URL – Select Web (if it isn’t already selected).
    4. Redirect URL (Should not be left empty) – Add the redirect URL for the redirection after authorization. This should be the same as mentioned in the SSO settings page of the OAuth and OpenID. You can find the redirect URL from the SSO configuration page under the label Single Sign On URL.
      Example: “http://${domain}/testrail/index.php?/auth/redirect_oidc_acs”
    5. Click Register.
  6. Add additional information in the Branding tab under the Manage section.
  7. Under the Authentication tab, configure additional login and logout URLs if needed.
  8. In Certificates and Secrets: 
    1. Create Secret – Click New Client Secret.
    2. Fill Description and expiration time – Click Add.
    3. Client Secret – Client Secret is the Value.

     

    Copy the client Secret Value before you leave this page, you will need it later.

  9. In Overview and Client ID, under the Overview section, you can find the Client ID’s, Tenant ID’s and other information. Under Overview, you can find the client ID.

     

    Copy the Client ID and Tenant Id, you will need it later.

  10. Users need to be added to have access to this APP in the Users section.

     

    You can find the reference document here: https://docs.microsoft.com/en-us/graph/tutorials/php?WT.mc_id=Portal-Microsoft_AAD_RegisteredApps&tutorial-step=2

Configuring SSO in Azure – OpenID Connect

  1. Login to TestRail as an administrator.
  2. Go to Administration -> Site Settings -> SSO.
  3. Select Your Authentication Protocol: OpenID Connect.
  4. Single Sign On URL: Prefilled with values that will be used to set the redirect URL during the new registration of the application.
  5. Login to your Azure portal and access your application to get the information in the next steps.
  6. Back on TestRail, for Client ID: Copy the Application (client) ID from the Azure Overview tab to paste it in this space.
  7. Client Secret: Copy the client secret Value from the Azure Certificates and Secrets to paste it in this space.
  8. IDP Issuer URL: Copy the Directory (tenant) ID from the Azure Overview tab and fill in this URL: https://login.microsoftonline.com/${yourTenantId}/v2.0/
  9. Create Account on First Login: Enable this setting to specify if TestRail should automatically create new user accounts in TestRail if a user could be successfully authenticated.
  10. Whitelist Domains: Restricting new account creation to certain email domains can be used to prevent requests from unauthorized organizations. Simply enter one domain per line. (If Whitelist Domain is empty, all are allowed by default.)
  11. Click Save Settings.

Configuring SSO in Azure – OAuth 2.0

  1. Login to TestRail as an administrator.
  2. Go to Administration -> Site Settings -> SSO.
  3. Select Your Authentication Protocol: Oauth 2.0
  4. Single Sign On URL: Prefilled with values that will be used to set the redirect URL during the new registration of the application (see step 5 above in Azure SSO Configuration).
  5. Login to your Azure portal and access your application to get the information in the next steps.
  6. Back on TestRail, for Client ID: Copy the Application (client) ID” from the Azure Overview tab to paste it in this space.
  7. Client Secret: Copy the client secret Value from the Azure Certificates and Secrets to paste it in this space.
  8. User Authorization URL: Copy Tenant ID: Copy the Directory (tenant) ID from the Azure Overview tab, and fill in this URL: https://login.microsoftonline.com/${yourTenantId}/oauth2/v2.0/authorize
  9. Access Token URL: Copy Tenant ID: Copy the Directory (tenant) ID from the Azure Overview tab, and fill in this URL: https://login.microsoftonline.com/${yourTenantId}/oauth2/v2.0/token
  10. User Info URL: Copy the URL https://graph.microsoft.com/oidc/userinfo and paste it in this space.
  11. Create Account on First Login: Enable this setting to specify if TestRail should automatically create new user accounts in TestRail if a user could be successfully authenticated.
  12. Whitelist Domains: Restricting new account creation to certain email domains can be used to prevent requests from unauthorized organizations. Simply enter one domain per line. (If Whitelist Domain is empty, all are allowed by default).
  13. Click Save Settings.

Configuring SSO in Azure – SAML 2.0

 

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. Select Your Authentication Protocol: SAML 2.0.
  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

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

 

TestRail – Configuring SSO

  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 IDP SSO URL, input the URL provided by Azure from step 11.
  5. Under IDP Issuer URL, input the URL provided by Azure from step 12.
  6. Under IDP Certificate, input the certificate text provided by Azure from step 13.
  7. Enable Authentication Fallback or Create Account on First Login, if preferred.
  8. Click Save Settings.
Was this article helpful?
2 out of 11 found this helpful