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

Okta 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 Okta protocol configuration. Follow these instructions first for the Okta web application registration:

  1. Sign in to your Okta organization with your administrator account.
  2. In the Admin Console, go to Applications > Applications. (It can be found on the left panel.)
  3. Click Create App Integration.
  4. Create a new app integration: 
    1. Sign-on method: Select OIDC – OpenID Connect.
    2. Application type: Select Web Application.
    3. Click Next. You have your Application registered and redirected to configure the application details.
  5. New Web App Integration:
    1. App integration name: Enter a name for your new app integration.
    2. Grant type: Authorization Code should be selected (this provides maximum security).
    3. Sign-in redirect URLs (Should not be left empty) – Here we need to 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
    4. Sign-out redirect URL (Optional):  https://{domain}/index.php
    5. Add any other additional information and click Save.
  6. To get the client credentials for your app integration:
    1. On the General tab, copy the Client ID from the Client Credentials section. 
    2. Copy the Client secret from the Client Credentials section. 
    3. Copy the Okta domain from the General Settings section.
  7. Enable Consent Screen in Okta:
    1. Go to Security -> API -> from the left panel.
    2. Click on Default.
    3. Go to the Scopes tab.
    4. Edit OpenID: User consent – Mark as checked and save.
    5. Edit Profile and email: User consent – Mark as checked and save.

Configuring SSO in Okta – 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. Log in to your Okta account and access your application to get the information on the next steps.
  6. Back on TestRail, for Client ID: Copy the Application (client) ID from the Client Credentials section of the Okta General tab and paste it into this space.
  7. Client Secret: Copy the client secret Value from the Client Credentials section of the Okta General tab and paste it into this space.
  8. IDP Issuer URL: Copy the Okta domain from the Okta General Settings section and fill in this URL https://${yourOktaDomain}/oauth2/default/
  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.
  12. Check the additional configuration settings below

Configuring SSO in Okta – 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.
  5. Log in to your Okta account and access your application to get the information on the next steps.
  6. Back on TestRail, for Client ID: Copy the Application (client) ID from the Client Credentials section in the Okta General tab and paste it into this space.
  7. Client Secret: Copy the client secret Value from the Client Credentials section in the Okta General tab and paste it into this space.
  8. User Authorization URL: Copy the Okta domain from the General Settings section in the Okta General tab and fill in this URL https://${yourOktaDomain}/oauth2/default/v1/authorize
  9. Access Token URL: Copy the Okta domain from the General Settings section in the Okta General tab and fill in this URL https://${yourOktaDomain}/oauth2/default/v1/token  
  10. User Info URL: Copy the Okta domain from the General Settings section, in the Okta General tab and fill in this URL https://${yourOktaDomain}/oauth2/default/v1/userinfo
  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.
  14. Check the additional configuration settings below

Additional Steps Configuring SSO in Okta – for OpenID Connect and OAuth 2.0 protocols ONLY

As published by Okta in their article, the following addiitonal steps must also be configured for instances using OpenID and OAuth protocols:

  1. Open admin OKTA portal
  2. Open Security → API page and on Authorization Servers tab click Edit button near your authorization server
  3. In the opened page go to Access Policies tab and click Add Policy button
  4. Populate Name, Description fields and click Create Policy
  5. In the newly created policy click Add Rule button
  6. In the appeared dialog populate Rule Name field, other settings can be left as is or changed as needed then click Create Rule.

Configuring SSO in Okta – SAML 2.0

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

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

     

    The values above are case-sensitive.

  12. Click the Next button in Okta and fill out the questionnaire or other remaining fields as required.
  13. 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.
  14. 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 and IDP Issuer URL fields respectively.
  15. Copy and paste (or download and then upload) the X.509 Certificate from Okta into TestRail.
  16. Click Save. Test your connection to verify the settings.
  17. So long as the administrator you are using to configure the settings in TestRail is assigned to the app you created in Okta, the connection test should succeed and you are now ready to use TestRail in Single Sign-On (SSO) mode.
Was this article helpful?
0 out of 0 found this helpful