Users, Groups, Permissions, Tokens, Authentication, and Authorization: Core Concepts and Mental Model

1. The practical problem: identity is not authorization

Earlier chapters used project-analysis tokens, user tokens for IDE/API scenarios, provider identities, and CI secrets. Chapter 21 turns those examples into a governed identity model. The central mistake to avoid is assuming that “this user can log in” means “this user should be able to administer, browse, analyze, or change every project.”

SonarQube authorization is layered. A person or automation first has an identity. Authentication proves that identity. Group membership and direct grants then determine global and project permissions. Finally, the requested UI, API, or scanner operation checks those permissions. A token does not create new authority; it acts within the authority attached to its owner/type and may be further bounded by token type.

2. Mental model: who are you, what can you do, and where?

flowchart TD
  I[Identity] --> A[Authentication]
  A --> G[Group memberships]
  A --> D[Direct user grants]
  G --> P[Effective permissions]
  D --> P
  P --> V{Global or project scope?}
  V -->|Global| X[Instance-wide action]
  V -->|Project| Y[Project action]
  T[Token type / owner] --> A
  Y --> Z[UI / Web API / scanner result]
  X --> Z

The arrows matter. Authentication happens before authorization. Group membership and direct grants are additive: a deny is normally represented by the absence of a grant, not by a separate “negative permission” that cancels another group. Therefore, a user who belongs to one overly broad group can retain more authority than an administrator expects even after a narrower direct grant is removed.

3. State map to capture before making changes

4. Users and groups: permissions accumulate

Current Community Build uses groups to make permission management scalable. A user can belong to several groups, and the user’s effective permissions are the union of permissions granted directly plus permissions granted through every group. Two built-in groups deserve special attention:

• sonar-users contains authenticated users. Current documentation notes that global Execute Analysis is granted to this group by default on a fresh installation; review this default against your organization’s policy.
• sonar-administrators contains the default administrator and should remain tightly controlled.

5. Global permissions: instance-wide authority

Global permissions are not tied to one project. Current Community Build documentation includes:

Use project-level Execute Analysis and project-analysis tokens where a job only needs to analyze one project. A global permission is not a convenience flag; it changes the blast radius of a compromised identity.

6. Project permissions and visibility

Project permissions apply to a specific project. Current Community Build documentation includes Browse Project, See Source Code, Administer Issues, Administer Security Hotspots, Administer project, and Execute Analysis on project. Chapter 15 already covered the 2026 Security Hotspot migration; the permission label may remain visible while finding semantics evolve, so record the actual release/UI rather than freezing automation to one object name.

New projects are public by default in current documentation. For a least-privilege enterprise-style model, private visibility makes authorization visible and testable: Browse and See Source Code must then be granted intentionally.

7. Permission templates: policy at project creation

A permission template defines default project-related grants for users/groups. A template can be the default or match project keys using a regular expression. When multiple templates match the same new project key, SonarQube reports an error rather than choosing ambiguously.

Template: SQ Chapter 21 Alpha
Project key pattern: ^sq-ch21-alpha-.*
Group: sq-ch21-alpha-devs
  Browse Project: yes
  See Source Code: yes
  Execute Analysis on project: yes
Administer project: sq-ch21-alpha-admins only

A template is SonarQube authorization policy. It is not a scanner property, not Git metadata, and not a Quality Gate. Changing it does not retroactively prove that a previous analysis ran under the new permission set.

8. Token types: narrow by purpose

Current documentation encourages project-analysis tokens because leakage is bounded to one project. Token values are shown only at creation. Users can choose an expiration; Enterprise edition and above can enforce a maximum lifetime for newly generated tokens. In Community Build, explicitly choosing an expiration and maintaining a consumer inventory is a governance control even when the server cannot enforce an organization-wide maximum.

9. Web API authentication and expiration evidence

Current Web API guidance recommends bearer authentication with a user token for API operations. API responses authenticated by a token can include SonarQube-Authentication-Token-Expiration, which automation can monitor to rotate credentials before expiry.

# Read-only example. SQ_USER_TOKEN is a limited user's token, not an admin token.
curl -fsS -D evidence/api-headers.txt \
  -H "Authorization: Bearer $SQ_USER_TOKEN" \
  "$SONAR_HOST_URL/api/measures/component?component=sq-ch21-alpha-app&metricKeys=ncloc" \
  -o evidence/measures.json

grep -i '^SonarQube-Authentication-Token-Expiration:' evidence/api-headers.txt || true

Web API V2 is gradually replacing older endpoints. Always use the in-instance API documentation for write operations and avoid hard-coding deprecated administrative endpoints into long-lived automation.

10. Authentication failure is not authorization failure

Preserve the actual HTTP status/body or scanner error from the current release. The diagnostic principle is the important part: first prove whether the identity was accepted, then prove whether that accepted identity was authorized for the requested operation.

Knowledge check

Official references and version notes

• Managing permissions — Community Build — current global/project permissions, default sonar-users Execute Analysis grant, visibility, and permission templates.
• Managing groups — additive direct/group permission model and built-in groups.
• Managing your tokens — user/project/global analysis token types, expiration, revocation, and owner-permission dependency.
• Administering tokens — administrator generation/revocation responsibilities.
• User accounts — built-in/delegated authentication and forced-authentication guidance.
• Web API — bearer authentication, token-expiration response header, form-data guidance, and Web API V2 transition.
• Current SonarQube downloads — Community Build 26.9.0.129388 baseline.
• SonarScanner CLI 8.1.0.6389 — scanner baseline used by the local analysis proofs.