Okta SSO Configuration

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 typeAuthorization 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 OpenIDUser consent – Mark as checked and save.
    5. Edit Profile and emailUser 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.

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.

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