qTest OnPremise: Replace Signed Certificate File for qTest SSO Integration

qTest Manager SSO Service Provider (SP) uses an x509 certificate to sign authentication requests and decrypt SAML assertions. As part of qTest Manager's security process, we update our Service Provider certificate every 3 years in August.

OnPremise customers need to complete the steps below to update the qTest keystore in the WAR package on your server.

Prerequisite

There is the possibility, you might have a patch applied to your qTest Controller (qtestctl) and the patch process in the past could prevent the new WAR package to be used properly. To verify, look into your qtestctl/manager/build.gradle and see if there is an "exclude" instruction with the WEB-INF. If so, contact Tricentis Support for assistance, and also send along your qtestctl/manager/build.gradle file.

Example:

This is what your qTest Manager build.gradle would look like if it was patched using the aforementioned method.

Download qtest Keystore

  1. Download the new qTest keystore at https://qtest-storage.s3.amazonaws.com/tools/keystores/qtest3y.jks

  2. Upload it onto your qTest Manager server. Compare the keys below to the downloaded versions, to ensure they match before proceeding.

    • sha1sum: d777ddac924cbd152eadd4839cc56f1d01471b4d

    • sha256sum: 76e4ecbac09583c52306fd2a824e24d17dc2bbe697667c017a088ed0f8193ee2

Locate qTest Manager WAR Package

Locate your qTest Manager WAR package inside your current qTest deployment.

If you find more than 1 qtest WAR package in the above locations. You can check for the currently used version by going into $YOUR_QTEST_URL/version using a web browsing tool like a web browser or cUrl. Your target qTest Manager WAR file will have the same version with "version" property returned from $YOUR_QTEST_URL/version.

qTest Docker

The location is at docker-deployment-x.x/dist/qtest/x.x.x/qtest-x.x.x.war

qTest Controller

The location is at qtestctl/.gradle/libs/qtest-x.x.x.war

Replace qTest Keystore Inside WAR Package

If you have multiple qTest Manager instances, you must replace the qTest Keystore for all of them.

Any extraction tool that can work with a ZIP archive can be used to work with a WAR package. In this guide, we use 7z on Windows and unzip on Linux.

Proceed to replace the qTest keystore inside the qTest Manager WAR package using an extraction tool:

qTest Controller on Windows

  1. Using 7z on Windows to open the WAR package (qtestctl/.gradle/libs/qtest-x.x.x.war) then navigate to qTest keystore's location (qtest-x.x.x.war\WEB-INF\security\)

  2. Drag and drop the new keystore into the extraction tool window, with the same name and the tool will replace it for you.

  3. Restart your qTest Manager server.

qTest Controller or qTest Docker on Linux

  1. Navigate to qTest Manager WAR file under the following location:

    • qTest Controller on Linux: qtestctl/.gradle/libs

    • qTest Docker on Linux: docker-deployment-x.x/dist/qtest/x.x.x

  2. Place the new keystore in the same directory with qTest Manager WAR package. Run the command and check the result similar to the following:

    [root@db 8.4.4]# ls
    qtest3y_new.jks qtest-8.4.4.war

  3. Execute the following shell command in order to replace the keystore. Notice the blue text in the example below, are instructions to verify you have successfully replaced the keystore.

    [root@db 8.4.4]# unzip -l qtest-8.4.4.war | grep jks # check the property of your current qTest keystore
    2547 05-11-2017 08:30 WEB-INF/security/qtest3y.jks
    5687 05-11-2017 08:30 WEB-INF/security/qtest.jks
    1256 05-11-2017 08:30 WEB-INF/security/localhost.jks
    [root@db 8.4.4]# mkdir -p WEB-INF/security # we MUST place the new keystore in the same directory 
structure with inside the WAR package for the zip replace command to work correctly
    [root@db 8.4.4]# mv qtest3y_new.jks WEB-INF/security/qtest3y.jks
    [root@db 8.4.4]# zip -r qtest-8.4.4.war WEB-INF/security/qtest3y.jks # replace whatever inside the 
WAR package with the provided file, at the same location inside the package
    updating: WEB-INF/security/qtest3y.jks
    zip warning: Local Entry CRC does not match CD: WEB-INF/security/qtest3y.jks
    (deflated 7%)
    [root@db 8.4.4]# unzip -l qtest-8.4.4.war | grep jks # double check the file size and timestamp 
to make sure the keystore has been replaced correctly
    2288 08-30-2019 02:35 WEB-INF/security/qtest3y.jks
    5687 05-11-2017 08:30 WEB-INF/security/qtest.jks
    1256 05-11-2017 08:30 WEB-INF/security/localhost.jks
    [root@db 8.4.4]# ls -la WEB-INF/security/qtest3y.jks
    -rw-rw-r--. 1 vagrant vagrant 2288 Aug 30 02:35 WEB-INF/security/qtest3y.jks

  4. Important: qTest Docker cache removal

    For qTest Docker, its cache directory must be wiped clean of the current exploded qTest Manager deployment for it to re-deploy the content in the WAR file.

    • The current cache location can be found in the "cachedir" property inside your docker-deployment-x.x/profiles/default.in

    • To reduce the impact, we wipe the cache of qTest Manager only, which is $cachedir/qtest/$QTEST_VERSION

  5. Restart qTest Manager server.

Next Steps:

Update qTest Manager SSO Service Provider Certificate on SSO IdP