In order to do global configuration, it is necessary to be logged in as a global administrator.

Plugin Mechanism

SonarQubehas been designed to be extensible. Since we believe in the 'eat your own food' philosophy, SonarQube is a suite of plugins that use the extension mechanism.

In order to configure these plugins, log in as an administrator, go to Settings > Configuration > General Settings.

Backup / Restore

The whole SonarQube configuration can be backed up and restored. This includes: Quality profiles (rules + alerts), manual metrics, events categories, global settings section (plugins) and customization.

WARNING When restoring , it will wipe ALL existing configuration No information about project configuration gets backed up (exclusions, links, quality profile associated...)

Overview

The Quality Profiles service is the heart of SonarQubeas it is where you define your requirements on:

• Files by defining sets of coding rules to check (ex: A method must not have a complexity greater thant 10)
• Projects by defining sets of measures thresholds (alerts) to comply with (ex: The number of new critical issues must not be greater than 0)

You can define as many quality profiles as you want. Indeed, the requirements are usually not the same while developing an application from scratch or maintaining an application which is 10 years old, while developing a technical framework or a web application. Then you can associate several quality profiles (one per language) to each project.

To manage quality profiles, go to Quality Profiles (top bar):

Security

The Quality Profiles service can be accessed by any users (even anonymous users) but any changes (create, edit or delete) require to be logged in as a System administrator or a Quality Profile administrator (since version 3.6).

A project administrator can only change the quality profiles associated to its project(s). See Project Administration#SettingQualityProfiles.

Creating Profile

To create a quality profile, click on the Create button on the upper right and enter the name of the quality profile:

You can optionally provide some Checkstyle, PMD and Findbugs configuration files to fill the new quality profile with some existing rules configurations.

Editing Profile

Configuring Rules

Go to the Coding rules tab. As there are numerous available coding rules, a search engine is available:

A coding rule can be activated or deactivated. Its severity and parameters can be modified:

Some bulk change actions are available to quickly activate or deactivate a set of rules:

No extra validation action is required to make changes to the quality profile.

Status of Rule

Since version 3.6, to help you choose which coding rules to activate, each rule has a status:

• Beta: The coding rule has been recently implemented and we haven't get enough feedback from users yet. So, it may log some false positives or generate some false negatives.
• Deprecated: The coding rule should no longer be used as a similar one, more powerful and accurate, exists.
• Ready: The rule is ready to be used in production.

Date of Creation of Rule

Since version 3.6, to help you spot the new coding rules, each rule has a creation date:

Multiple Activations of a Rule

Some coding rules can be activated multiple times in the same quality profile with different parameters values. XPath rule is one of this kind.

If a rule can be activated multiple times, a Copy button is available:

Clicking on the Copy rule link displays a form to define the new rule:

Once the new rule has been created, it can be managed as any other rules.

Editing Alerts

To manage alerts configuration, got to the Alerts tab: 



From there, it is possible to fully manage alerts, by adding new ones, editing or deleting existing ones. Choose:

• the metric you are interested in
• whether the alert will be checked against the current value of the measure or the variation of this measure (available since version 3.4)
• an operator (is greater than, is less than, etc.)
• the value that will trigger a warning
• the value that will trigger an error

Any changes will apply during the next analysis.

Profile Inheritance

Maintaining lots of quality profiles over time can be tedious. To ease this maintenance, quality profiles can be inherited. For each profile, you can decide whether it has a parent profile or not on the Profile Inheritance tab:

This means that the quality profile inherits from all the coding rules defined in the parent one. This is shown on the Coding rules tab by a small blue marker next to the coding rule:

A rule inherited from a parent cannot be deactivated. But it is possible to change its parameter(s) and/or its severity. As soon as one of these values is changed, a red marker replaces the blue marker:

Changes made to an inherited coding rule can be reverted by clicking on the Revert to parent definition button:

Alerts are not inherited from parent profiles.

Extending Rule Description

• Extend the description of a rule to give more details, add an internal description, etc. This is going to be attached to the rule in every quality profile and will also be available when clicking on an issue:

• Add a comment, in the context of a specific quality profile, explaining the reasons of the activation of the rule, it severity, etc. 

Associating Project to Quality Profile

To associate/dissociate projects to/from a quality profile, go to the Projects tab:

When a project is not explicitly associated to a quality profile, the default quality profile is used to perform the next analysis.

Backuping/Restoring Profile

This backup/restore mechanism is useful for instance to promote a quality profile from a staging environment to a production one or to share quality profiles with subcontractors.

Click on the Backup button to export an XML file.

To restore a quality profile, click on the Restore profile link on the top right of the Quality profiles page, choose the XML file to restore and click on the Restore profile button:

Copying Profile

In order to copy an existing quality profile, click on the Copy button next to the profile you want to copy. You are prompted to give the name of the new profile. The profile is the exact copy of the copied one. You can then make desired changes to the new quality profile.

Renaming Profile

Click on the Rename button. You are prompted to give the new name of the profile.

Deleting Profile

Click on the Delete button. You are prompted to confirm the deletion.
Deleting a quality profile will delete the alerts defined in the profile and will remove the association with projects. If nothing else is done, the default profile is used to perform the next analysis on the (ex-)associated projects.

Comparing Profiles

It is possible to compare 2 quality profiles to understand the differences between them:

The comparison service shows all differences (rules in one profile but not in the other, parameters differences, etc.):

Profile Change Log

Every time a change is made to a quality profile, it is going to appear in the change log:

Extending Coding Rules

Custom coding rules can be added. See Extending Coding Rules for detailed information and tutorials.

SonarQube comes out of the box with a complete mechanism to manage security. Configuring security enables to cover two main use cases:

• Manage access rights to resources, information, etc.
• Enable customization (custom dashboards, notifications, etc.) of SonarQube for users

Built-in Security

Authentication

Default Admin Credentials

When installing SonarQube, a unique user gets created:

• Login: admin
• Password: admin

Log in and click on your name (top right of the screen).

LDAP plugin When the LDAP plugin is installed and activated, it is no longer possible for users to change their password. Then, only system administrators can do so through Settings > Security > Users.

Authorization

The way authorization is implemented in SonarQube is pretty standard. It is possible to create as many users and groups of users as required in the system. The users can then be attache (or not) to (multiple) groups. Groups and / or users are then given (multiple) roles. The roles grant access to projects, services and functionalities.

Groups

Overview

A group is a set of users.

To create a new group, go to Settings > Security > Groups > Add new group:

To add/remove users to/from a group:

Special groups

Two groups have a special meaning:

• Anyone is a group that exists in the system, but that cannot be managed. Every user belongs to this group.
• sonar-users is the group to which users are automatically added. This group can be changed through the Global Security Settings (sonar.defaultGroup property).

Roles

Overview

There are 5 different roles, 2 are global, the 3 others are defined at project level:

• Global roles:
  • System Administrators have the ability to perform all administration tasks on the SonarQube instance like global configuration, customization of the home page, etc.
  • Quality Profile Administrators have the ability to perform any changes on quality profiles (since version 3.6)

• Project roles:
  
  • Administrators have the ability to perform administration tasks for the project by accessing its settings
  • Users have the ability to browse the measures and to create/edit issues on the project
  • Code viewers have the ability to view the source code of the project

Note that roles are not cumulative. For instance, if you want to be able to administer the project, browse the measures and browse the source code, you have to be given the three roles: Administrator, User and Code Viewer.

Default project roles

It is possible to configure the system so that when a new project is created, some users/groups are automatically granted roles on this project.

In the example below, once a new project has been created:

• All the users in the sonar-administrators group can administrate (Administrators), access the project (Users) and browse the source code (Code viewers).
• The myAuditor user can access access the project (Users) and browse the source code (Code viewers).

Security Settings

1. Default user group: any new user created will automatically join this group.
2. Force user authentication: this is really the first question that should be answered when setting the security strategy in SonarQube. Can anybody browse the SonarQube instance or do you need to be authenticated?
3. Allow users to sign up online: this means that anybody can access a form to create himself an account in the system. Note that after filling up the form, the user should log in.
4. Import sources: if set to false, source code will not be accessible for any user, to restrict access to source code for some users only, see Code viewers role.

Delegation to an External System

In order to leverage existing enterprise infrastructure, SonarQube provides the capability to delegate authentication and authorization to external systems through plugins:

• LDAP with the SonarQube LDAP Plugin
• Active Directory with the SonarQube LDAP Plugin
• PAM with the SonarQube PAM Plugin
• Crowd with the SonarQube Crowd Plugin

Settings Encryption

Encryption is mostly used to remove clear passwords from settings (database or SCM credentials for instance). The implemented solution is based on a symetric key algorithm. The keypoint is that the secret key is stored in a secured file on disk. This file must only be owned and readable by the system account that runs the SonarQube server, the analysis with SonarQube Runner, SonarQube Ant Task, Maven or from the Continuous Integration server.

The algorithm is AES 128 bits. Note that 256 bits cipher is not used because it's not supported by default on all Java Virtual Machines (see this article).

1. Generate the secret key

A unique secret key must be shared between all parts of the SonarQube infrastructure (server and analyzers). To generate it, go to Settings > Configuration > General Settings > Encryption and click on Generate secret key:

2. Store the secret key on the SonarQube server

1. Copy this secret key in a file:

   sonar-secret.txt

   
   
   

2. Store this file on the machine hosting the SonarQube server (default location:  ~/.sonar/sonar-secret.txt). If you want to store it somewhere else, set its path through the sonar.secretKeyPath property in SONARQUBE_HOME/conf/sonar.properties:

   SONARQUBE_HOME/conf/sonar.properties

   
   
   

3. Restrict its access to the system account running the SonarQube server (ownership and read-access only).
4. Restart your SonarQube server.

3. Generate the encrypted values of your settings

Go back to Settings > Configuration > General Settings > Encryption and generate the encrypted values or your settings:

4. Use these encrypted values

Server side

Simply copy these encrypted values into SONARQUBE_HOME/conf/sonar.properties:

Restart your SonarQube server.

Batch side

Copy the secret key file on the machine running the analysis.

Copy these encrypted values into the analyzer configuration file: sonar-runner.properties, settings.xml, etc. Do not forget to define the path to your secret key as well.

The sonar.password property is not encryptable. See SONAR-4061.

FAQ

I have locked myself out

There is currently nothing that stops you removing from every user and every group the global administrator role. the global administrator role. You then have no other solution than make an manual update in the SonarQube database to get back in control.

I have lost the admin password

In case you lost the admin password of your SonarQube instance, you can reset it by running the following update statement :

This will reset the password to admin.