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

1. Go to Google Dashboard: https://console.cloud.google.com/apis/dashboard
2. Registration: Create a Project in Google API Console.
   1. Click  CREATE PROJECT.
   2. Fill in the Project Name, Organization, and Location, and click Create.
3. Dashboard: Select your Project from the navigation bar (marked as a in the picture below).

   

4. OAuth Consent screen: Configure the OAuth Consent Screen by selecting it from the left panel (marked as c in the above picture).
   1. Provide App Information, App Domain, and Developer Contact Information. Click Save and continue.
   2. Scopes – Add scopes as OpenID, email, and profile. Click Save and continue.
   3. Provide the Optional Information.
   4. Verify the details and confirm if asked.
5. Credentials: Click on Credentials on the left navigation panel (marked as b in the above picture).
   1. Click Create Credentials and select OAuth client ID.
   2. Select Application type (Web Application in our case).
   3. Provide a name.
   4. Authorized redirect URLs: 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: “https://${domain}/testrail/index.php?/auth/redirect_oidc_acs” 
   5. Click Create.
   6. A popup will appear containing the Client ID and Client Secret to be copied for configuration.
   7. The Client ID and secret can be later copied from the Credentials tab.
      1. Under OAuth 2.0 Client IDs, select the credentials. A new page will appear, with the client ID and secret on the right panel.
      2. Here you can add/ remove/ edit the Redirect URL as well.

Configuring SSO in Google – 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 authentication of APP in Google.
5. Login to your Google Dashboard 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 Google Credentials tab to paste it into this space.
7. Client Secret: Copy the client secret Value from the Google Credentials tab to paste it into this space.
8. IDP Issuer URL: Copy the URL https://accounts.google.com/ and paste it in this space. 
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 Google – 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 authentication of APP in Google.
5. Login to your Google Dashboard 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 Google Credentials tab to paste it into this space.
7. Client Secret: Copy the client secret Value from the Google Credentials tab to paste it into this space.
8. User Authorization URL: Copy the URL https://accounts.google.com/o/oauth2/v2/auth and paste it into this space.
9. Access Token URL:  Copy the URL https://oauth2.googleapis.com/token and paste it into this space.
10. User Info URL: Copy the URL https://openidconnect.googleapis.com/v1/userinfo and paste it into 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 Google – SAML 2.0

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

1. Access your Google Admin Console.
2. Under the Dashboard, click on Apps and select SAML apps.
3. Click Add a service/App to your domain and select the Setup my own custom app option.
4. Save the SSO URL for later use.
5. Save the Entity ID URL for later use.
6. Download the Certificate, open using a text editor or notepad, and save this for later use.
7. Click Next, name your Application TestRail, and click Next again.
8. Under ACS URL, provide the Single Sign-on URL from step 5.
9. Under Entity ID, provide the Entity ID metadata URL from step 4.
10. Leave all the default options alone and select Next.
11. 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

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

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 Google from Step 12.
5. Under IDP Issuer URL, input the URL provided by Google from Step 13.
6. Under IDP Certificate, input the certificate text provided by Google from Step 14.
7. Enable Authentication Fallback or Create Account on First Login, if preferred.
8. Click Save Settings.