Secrets, Tokens and Credentials in SonarQube

This document lists all secrets, tokens and credentials that can be configured and managed by a non-administrator user in SonarQube.

For each item, a concise explanation of its usage and a link to the official documentation are provided.

User Token

Description

Authentication token that allows a user to perform all actions the user can do via the web interface, without using their actual credentials (login/password).

• Invoke SonarQube Web APIs (via Bearer or Basic HTTP authentication)
• Run code analyses
• Configure SonarLint/SonarQube for IDE in Connected Mode (mandatory) Inherits all permissions of the user who created it.

For example, a User Token from a global administrator gives full rights to the instance.

Configuration

• Where to create:
  • User > My Account > Security
• Parameters:
  • Token name, Type (User), Expiration date (recommended)
• Usage:
  • sonar.token property or SONAR_TOKEN environment variable for analyses
  • in HTTP header for API calls

Official Documentation

• Managing your tokens - Latest
• Authentication tokens - Latest

Project Analysis Token

Description

Project-specific authentication token that allows running analyses only on that particular project.

• Run code analyses on the specified project
• Invoke Web Services requiring “Execute Analysis” permission on the associated project Limited to the specific project it was created for.

If the token author loses “Execute Analysis” permissions on the project, the token becomes invalid.

Configuration

• Where to create:
  • User > My Account > Security
• Parameters:
  • Token name, Type (Project Analysis Token), Associated project, Expiration date (optional)
• Usage:
  • sonar.token property or SONAR_TOKEN environment variable for project analyses

Official Documentation

• Managing your tokens - Latest
• Project Analysis Token section

Global Analysis Token

Description

Authentication token that allows running analyses on all projects in the SonarQube instance.

• Run code analyses on any project in the instance
• Useful for multi-project CI/CD pipelines Valid for analyzing all projects.

If the token author loses the “Global Execute Analysis” permission, the token becomes invalid.

Configuration

• Where to create:
  • User > My Account > Security
• Parameters:
  • Token name, Type (Global Analysis Token), Expiration date (optional)
• Usage:
  • sonar.token property or SONAR_TOKEN environment variable for analyses

Official Documentation

• Managing your tokens - Latest

Token recommandations

Secure interactions with SonarQube require attention to token management practices. Below are some best practices to help maintain a secure environment:

Webhook Secret

Description

Webhooks are used to notify external services when a project analysis is done. An HTTP POST request including a JSON payload is sent to each of the provided URLs. Optional secret used to secure webhooks by generating an HMAC-SHA256 signature that verifies the authenticity and integrity of payloads sent by SonarQube.

• Secure webhooks configured at project or global level
• Verify that requests actually come from SonarQube and not from an unverified source
• The HMAC signature is transmitted in the X-Sonar-Webhook-HMAC-SHA256 HTTP header

Configuration

• Where to configure:
  • Project: Project Settings > Webhooks
  • Global: Administration > Configuration > Webhooks (requires admin rights)
• Parameters:
  • Webhook name
  • Destination URL
  • Secret (random string of your choice)
• Usage:
  • The secret is used by SonarQube to create a hash with each payload. The third-party service must validate this signature.

Official Documentation

• Webhooks - Latest
• Securing your webhooks section

Project Badge Token

Description

Unique security token automatically generated for each project that allows displaying dynamic badges (metrics, Quality Gate status) on external web pages or third-party tools.

• Display a project’s Quality Gate status on a GitHub/GitLab README
• Expose specific metrics (bugs, vulnerabilities, code coverage, etc.) via a dynamic image
• Include in external websites or documentation

Configuration

• Where to configure:
  • Go to the project > Project Information (top right corner)
  • “Badges” section
• Parameters:
  • Information type: Metric value or Quality Gate status
  • Metric to display (if type is Metric value)
  • Format: Markdown or Image URL

Official Documentation

• Project badge - Latest
• Using a project badge

DevOps Platform Integration - Personal Access Token (PAT)

Description

Personal access tokens from DevOps platforms (GitLab) allowing SonarQube to connect to these platforms to import projects and decorate Pull/Merge Requests.

• Import GitLab projects into SonarQube
• Decorate Merge Requests with Quality Gate results
• Access and list user’s GitLab projects

Configuration

• Import:
  • Projects > Create project > From GitLab > Provide PAT with read_api scope
• MR Decoration:
  • Automatically configured during import, or manually in Project Settings > Pull Request Decoration

Official Documentation

• GitLab integration - Latest
• Importing GitLab repositories

Login/Password Authentication (Deprecated)

• Historically used for authentication in analyses (sonar.login and sonar.password properties)
• Still supported but discouraged