Latest | Analyzing source code | Various setups | Managing TLS certificates on client side

Was this page helpful?

Managing the TLS certificates on the client side

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 the SonarQube server by the SonarScanner.

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

For SonarScanner for Maven, Gradle, CLI, or NPM

You can either use:

Only for SonarScanner for Maven, Gradle, Ant, and for SonarScanner CLI before version 6.0 and SonarScanner for NPM before version 4.0: The default JVM truststore (\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.

See also: Self Signed certificate of DevOps platforms.
A custom Java truststore by using the following properties:
- javax.net.ssl.trustStore or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.truststorePath: path to the truststore file.
- javax.net.ssl.trustStorePassword or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.truststorePassword: password to the truststore.

Except for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0, where you can use regular sonar properties, you must define the properties by using the SONAR_SCANNER_OPTS environment variable.
Example (on Windows, use forward slashes as path separators):

SONAR_SCANNER_OPTS="-Djavax.net.ssl.trustStore=/repositories/tls-mutual-nginx/cacerts -Djavax.net.ssl.trustStorePassword=changeit"

For SonarScanner for .NET

Add the self-signed server certificate to the operating system truststore:

On Linux and MacOS:
1. Copy the self-signed server certificate to /usr/local/share/ca-certificates
2. Run sudo update-ca-certificates
On Windows: use certutil.
Example:

certutil -addstore -f "ROOT" <path/to/certificate>

In addition, since SonarScanner for .NET invokes SonarScanner CLI, you must add the self-signed certificate to the Java truststore as explained above.

If running the scanner with Docker

If you need to configure a self-signed certificate for the scanner to communicate with your SonarQube instance, you can use a volume under /tmp/cacerts to add it to the containers java trust store:

docker pull sonarsource/sonar-scanner-cli
docker run \
    --rm \
    -v ${YOUR_CERTS_DIR}/cacerts:/tmp/cacerts \
    -v ${YOUR_CACHE_DIR}:/opt/sonar-scanner/.sonar/cache \
    -v ${YOUR_REPO}:/usr/src \
    -e SONAR_HOST_URL="http://${SONARQUBE_URL}" \
    sonarsource/sonar-scanner-cli

Then, assuming both the cacerts and Dockerfile are in the current directory, create the new image with a command such as:

docker build --tag our-custom/sonar-scanner-cli .

If running the SonarQube scan GitHub Action

If you use the sonarqube-scan-action for your GitHub Action and your SonarQube server has root 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).

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 the TLS authentication of the SonarScanner by the SonarQube Server.

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.