Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Concepts and Setup

Users, Tokens and Permissions

Learn how SonarQube handles users and groups, the three token types, global and project permissions, and how to give CI the least privilege it needs to scan.

A SonarQube server is shared by developers, CI jobs and administrators, and each needs different access. The product separates who you are (users and groups), how a program proves it (tokens) and what you may do (permissions). Understanding the three keeps your server safe without making scans painful.

Users and groups

A user is an account, created locally or provisioned from an external identity provider (LDAP, SAML, or an OAuth login from GitHub, GitLab, Bitbucket or Azure DevOps). A group is a named set of users. Grant permissions to groups, not to individuals, so that joining a team gives the right access in one step.

Two built-in groups exist: sonar-administrators (full control) and sonar-users (every user belongs to it; its permissions apply to everyone). New accounts start in sonar-users.

Global and project permissions

Global permissions apply to the whole server. The important ones are Administer System, Administer Quality Gates, Administer Quality Profiles, Create Projects and Execute Analysis (run scans at all; the project-level permission is also needed on each project in some setups).

Project permissions apply to one project:

  • Browse: see the project and its issues.
  • See Source Code: view the code in the UI.
  • Administer Issues: change status, mark false positives.
  • Administer Security Hotspots: review hotspots.
  • Execute Analysis: upload a report for this project.
  • Administer: change settings, gate, profile of this project.

You can set defaults through permission templates, which apply to new projects automatically. A common template gives group developers Browse, See Source Code and Administer Issues, and gives a ci-scanners group Execute Analysis.

Python Resolve a user's effective permissions (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In the stand-in, administer implies everything on the project, which matches how the real Administer permission behaves for settings (it does not automatically give Execute Analysis in the real product; the stand-in simplifies). Always test the real behavior with a scratch account.

Tokens

Passwords do not belong in CI. A token is a long random string that stands in for a password and can be revoked on its own. SonarQube has three kinds:

  • User token (prefix squ_): acts as you, with your permissions. Good for personal scripts and for the first local scan.
  • Project analysis token (prefix sqp_): can only run analyses on one project. Ideal for CI.
  • Global analysis token (prefix sqa_): can run analyses on any project the creator may scan. Use it for a build farm that scans many projects, with caution.

Create tokens in your account page under Security, or for project tokens from the project's setup. The secret value appears only once. Give tokens an expiration where possible and store them in the CI secret store.

Python Recognize and mask tokens (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Using a token

The scanner reads it from SONAR_TOKEN or -Dsonar.token. For the Web API, send the token as the username of HTTP basic authentication with an empty password, or as a Bearer token in newer versions:

Terminal
curl -u "$SONAR_TOKEN:" "http://localhost:9000/api/qualitygates/project_status?projectKey=my-shop"

The colon after the token means "empty password". Logging a token anywhere (CI output, shell history) counts as leaking it: revoke it and create a new one.

Least privilege for CI

A recommended setup:

  1. Create a user ci-scanner (or a technical account) that belongs only to a group with Execute Analysis on the right projects.
  2. Create a project analysis token for each project, stored as a secret in that project's CI settings.
  3. Rotate tokens when people leave or when one may have leaked.
  4. Never use an administrator's user token in a pipeline.

Authentication choices

For a team of any size, connect single sign-on (SAML or the OAuth login for your code host) rather than managing local passwords. Turn on force user authentication so that anonymous visitors cannot browse code. Both are in Administration > Configuration > Authentication and Security; exact labels vary between versions, and later lessons on administration cover them more.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which token type is best for a CI job that scans a single project?

    A project analysis token can only run analyses on one project, which is the least privilege CI needs.
  2. 2. How many times does the server show the full token value?

    The value is displayed only at creation, so copy it into a secret store immediately.
  3. 3. Why grant permissions to groups instead of users?

    Group-based permissions scale: change one group and every member is updated.
  4. 4. What does the prefix sqa_ identify?

    sqa_ marks a global analysis token; squ_ marks user tokens and sqp_ project analysis tokens.

Summary

  • Users belong to groups; grant permissions to groups, with permission templates for new projects.
  • Global permissions manage the server; project permissions (Browse, See Source Code, Administer Issues, Execute Analysis, Administer) manage a project.
  • Use project analysis tokens for CI, and keep all tokens secret and rotatable.
  • Use single sign-on and force authentication on shared servers.

Next: The Issue Lifecycle