TLS certificates on client side

Information on server and client certificate-based authentication with SonarQube Server.

If your SonarQube Server instance is secured behind a proxy and a self-signed certificate, then you must add the self-signed certificate to the trusted CA certificates of the SonarScanner.

In addition, If mutual TLS is used, then you must define the access to the client certificate at the SonarScanner level.

Managing the self-signed server certificate

Introduction to server authentication

During the TLS authentication of the server, the client requests the server certificate from the server and verifies that this certificate is signed by a CA it trusts by checking its TrustStore. In case a self-signed server certificate is used, it must be added to the TrustStore of the client. The figure below shows the certificates involved in the authentication of SonarQube Server by the SonarScanner.

Adding the self-signed server certificate to the trusted CA certificates

Step 1: Add the certificate for your scanner

The way you add your self-signed certificate depends on your scanner.

SONARSCANNER FOR MAVEN

You can either:

• Insert your certificate in the default JVM TrustStore (something like \jre\lib\security\cacerts). To add the self-signed server certificate to the default TrustStore, use the JVM tool keytool. The instructions depend on your operating system and you will find many resources online, such as this one for Linux.

or:

• Provide a custom Java TrustStore. This operation depends on your scanner version:

  • Version >= 5.0: We recommend using the properties sonar.scanner.truststorePath and sonar.scanner.truststorePassword. If this does not work, please retry after upgrading to the next scanner minor version. You can also use the properties described below for version <= 4.0.

  • Version <= 4.0: Use the following properties:

    • javax.net.ssl.trustStore: path to the TrustStore file (pkcs12 format is recommended).

    • javax.net.ssl.trustStorePassword: password of the TrustStore.

The javax.net property is a JVM property, not a scanner property. It should be passed using the SONAR_SCANNER_OPTS environment variable. For example: SONAR_SCANNER_OPTS="-Djavax.net.ssl.trustStore=C:/ssl/truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit" (on Windows, use forward slashes as path separators).

SONARSCANNER FOR GRADLE

SONARSCANNER FOR .NET

SONARSCANNER FOR NPM OR CLI

For information about setting the mentioned sonar properties, see Using the scanner, Configuring the scanner, or SonarScanner CLI.

Step 2: Additional step depending on your CI tool

If you use GitHub Action or Azure Pipelines, an additional step is necessary as described below.

GITHUB ACTION

If you use the sonarqube-scan-action for your GitHub Action and your SonarQube Server instance has certificates that need to be recognized by the GitHub runner, you’ll need to set the SONAR_ROOT_CERT environment variable in GitHub.

To do this, go to your GitHub repository > Settings > Secrets and Variables and add the SONAR_ROOT_CERT environment variable in PEM format. You can also add it at the level of your GitHub organization (recommended).

Due to a known GitHub issue, if your GitHub Action v4 and above

• uses SONAR_ROOT_CERT

• and is executed in a containerized environment, for example when the job running the action declares container: <docker-image-name>

you need to explicitly set the SONAR_USER_HOME environment variable to be the "$HOME/.sonar".

You can do that by adding the following step before executing the action:

# Workaround for https://github.com/actions/runner/issues/863
- name: Workaround for containerized environments
  run: echo "SONAR_USER_HOME=$HOME/.sonar" >> $GITHUB_ENV
- name: Run sonar analysis
  uses: SonarSource/sonarqube-scan-action@<action version>
  ...

AZURE PIPELINES

Managing the client certificates

Introduction to client authentication

If mutual TLS is used then both the client and the server authenticate the other party. During the TLS authentication of the client, the client must provide its certificate with the corresponding CA certificate chain (intermediate and root CA certificates) to the server. The client manages its certificates in its own keystore. The figure below shows the certificates involved in SonarQube Server’s TLS authentication of the SonarScanner.

Defining the access to the client certificates

For SonarScanner for Maven, Gradle, CLI, or NPM

Store the client certificate and CA certificate chain in a keystore file and define the access to this file through the following properties:

• javax.net.ssl.keyStore or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.keystorePath: path to the keystore file.

• javax.net.ssl.keyStorePassword or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.keystorePassword: password of the keystore file.

For SonarScanner for .NET

1. Store the client certificate and CA certificate chain in a keystore file and define the access to this file through the following properties:

   • sonar.clientcert.path : path to the keystore file, must be set in the begin step.

   • sonar.clientcert.password: password of the keystore file, must be set in both the begin and end steps.

2. In addition, set the following options before the end step (for the SonarScanner CLI invocation):

   • javax.net.ssl.keyStore: same value as sonar.clientcert.path

   • javax.net.ssl.keyStorePassword: same value as sonar.clientcert.password