Configure qTest-Scenario with NGINX

As of qTest Scenario 3.3.0, Scenario can now be configured to work with NGINX. This article outlines how to set up this configuration.

Prerequisites

  • You need to have generated a Client and Server key pair.

    • You can find the instructions to find key here.

  • NGINX is properly configured and working as expected.

  • The account that setup Scenario must have the Global Administration permission

Requirements

Allowing access to all.js and all_debug.js

qTest Scenarios plug-in for Jira requires all.js and all_debug.js for conducting a secure channel so that Scenario Server can communicate with the plug-in (for more information about all.js and all-debug.js, refer to https://developer.atlassian.com/cloud/jira/platform/about-the-javascript-api/.

When the Jira Server is not behind the NGINX Server, the iframe of Scenario Plug-in will use the Jira Server BaseURL to construct a full URL to all.js and all-debug.js.

For example, if the Jira Server BaseURL is https://example.com, then the full URL to all.js will be https://example.com/atlassian-connect/all.js.

However, when the server is behind NGINX, the path will be changed to https://<NGINX Server base URL>/atlassian-connect/all.js which prevents the plug-in to work properly since NGINX will ask for authentication.

Therefore, in the NGINX configuration for Jira Server, use these lines to allow access to all.js and all-debug.js without authentication:

Copy 
location = /atlassian-connect/all-debug.js {
  proxy_pass <jira server base URL>/atlassian-connect/all-debug.js;
}

location = /atlassian-connect/all.js {
  proxy_pass <jira server base URL>/atlassian-connect/all.js;

}

NGINX self-signed certificate issue

To serve the resources over HTTPS, NGINX requires a private key and a public certificate. These can be generated internally.

However, the browser will not trust the certificates by default. This will prevent the Scenario Plug-in from loading all.js and all-debug.js through NGINX.

The symptoms are:

  • Iframe stuck loading

  • Console log of developer tools in the browser will throw errors related to all.js and all-debug.js

There are two ways to solve this issue:

  1. Using commercial certificates.

  2. Add the certificate to the trusted list of all the machines using Jira and Scenario through a browser. Read Install Self-signed Certificate To The Browser Guide for additional information.

Configure Scenario to work with Jira Server and NGINX

  1. From your Jira instance, select Jira System in the Gear button beside the account image.

  2. The Administrator page updates, select the Add-ons tab.

  3. Choose Manage add-ons at the left navigation panel.

  4. Select qTest Scenario - BDD for Jira add-on, and then choose Configure.

  5. Follow the instructions below that align with your configuration:

    • Configuration 1: NGINX without Client Certificate and OAuth 2.0

      1. Change the Jira Server Base URL to NGINX URL

      2. Click Save configuration.

    • Configuration 2: NGINX with Client Certificate

      1. Change the Jira Server Base URL to NGINX URL

      2. Configure certificate: Copy the content of the Client certificate file and key then paste to the corresponding text box. If the private key has a passphrase, then type it to the Passphrase field.

        We only support key decryption for pkcs8 format.

      3. Click Save configuration.

    • Configuration 3: NGINX with OAuth 2.0

      1. Change the Jira Server Base URL to NGINX URL

      2. Configure OAuth 2.0: Enter your Client ID and Client Secret to the corresponding ClientId and Client secret text box.

        We only support auth server Okta.

      3. Click Save configuration.

    • Configuration 4: NGINX with Client Certificate and OAuth 2.0

      1. Change the Jira Server Base URL to NGINX URL.

      2. Scroll down to the end.

        • Configure key pair: Copy the content of the Client certificate file and key then paste to the corresponding text box. If the private key has a passphrase, then type it to the Passphrase text box.

          We only support key decryption for pkcs8 format.

        • Configure OAuth 2.0: Enter your Client ID and Client Secret to the corresponding ClientId and Client secret text box.

          We only support server Okta.

  6. Select Save configuration.