Chapter 21Lesson 03~125 minutes

Users, Groups, Permissions, Tokens, Authentication, and Authorization: Configuration, Design Patterns, and Trade-Offs

Choose group-based RBAC, project/global permission boundaries, token types, visibility, and exception patterns using least privilege, portability, and auditability as design constraints.

IdentityRBACPermissionsTokensAuthorization

Learning objectives

Choose group-based RBAC over direct-user sprawl for normal team access.
Separate global authority from project authority and justify the few roles that need each.
Select user, project-analysis, or global-analysis tokens based on consumer and blast radius.
Design public/private project visibility deliberately rather than accepting defaults blindly.
Use templates and centralized ownership while preserving controlled exceptions and rollback.
Understand where external identity/provisioning ownership changes the configuration boundary.

1. Design principle: permission is a product of identity and scope

Least privilege is not achieved by creating many small tokens under one administrator account. The safer design starts with a bounded identity, gives that identity only the required group/project permissions, then chooses a token type that narrows the credential’s purpose further where possible.

bounded identity → group-based grants → project/global scope →
              narrow token type → explicit consumer → expiration/rotation →
              revocation proof

2. Group-based RBAC versus direct-user permissions

Approach	Benefits	Risks	Best fit
Group-based	Central ownership, easier onboarding/offboarding, reusable templates, auditable role intent	Over-broad groups can silently accumulate authority	Normal team access
Direct-user grant	Fast, precise exception	Sprawl, hidden exceptions, difficult offboarding	Temporary documented exception only

Direct grants are not forbidden; they are expensive governance objects. Attach an owner, reason, expiration/review date, and rollback to every exceptional grant.

3. Global versus project permissions

Use a global permission only when the job truly spans the instance. A build job for one application should not receive global Execute Analysis. A profile curator may need Administer Quality Profiles without Administer System. A project owner may need Administer project without global administration.

Scanner for one app

Project Execute Analysis + project-analysis token.

Central multi-project scanner

Global Execute Analysis + global-analysis token only if the architecture requires it and consumers are inventoried.

Project maintainer

Administer project for owned projects, preferably via group/template.

Quality governance

Dedicated global gate/profile permissions; avoid Administer System when not needed.

4. Analysis token versus broader user/API token

Project-analysis tokens are purpose-built for one project’s analysis. User tokens are broader because they inherit the issuing user’s full Web API authority. A user token can still be reasonably bounded when issued by a dedicated service user with narrowly designed group/project permissions, but the scope comes from the identity, not from per-token API scopes.

Credential design rule. First minimize the owner’s permissions; then choose the narrowest token type; then minimize lifetime and consumer count.

5. Public versus private project visibility

Current documentation says new projects are public by default. Public means anonymous or broad users may browse measures/issues/source according to the product’s visibility semantics. Private projects require explicit Browse and, separately, See Source Code permissions.

Choice	Use when	Evidence
Public	Source/project data is intentionally public and policy permits anonymous/broad visibility	Document public-data classification and default visibility
Private	Source, issues, or measures are confidential	Group-based Browse/Source grants and denial tests

Visibility is not a substitute for Execute Analysis permission. A user might be able to browse a public project yet still lack authority to push an analysis.

6. Permission templates as centralized policy

Permission templates reduce drift by applying a common grant pattern when projects are created. Project-key regular expressions can map ownership domains, for example ^payments-.* or ^sq-ch21-alpha-.*. Avoid overlapping regexes because current SonarQube treats multiple matches as an error.

Templates are especially useful when paired with group lifecycle controls: the template says what the role receives, while group membership says who currently holds the role.

7. Centrally managed versus exceptional permissions

Model	Owner	Change path	Rollback
Built-in local groups/templates	SonarQube admin/project admin	SonarQube UI/API	Reapply prior group/template state
Externally synchronized users/groups	IdP/provisioning system	External source of truth	Revert external assignment
Local exception	Explicit exception owner	Documented temporary direct grant	Remove on expiry/review

If authentication/provisioning synchronizes permissions automatically, current documentation warns that manual updates may be unavailable. Do not fight the synchronization layer; change the owning system. Chapter 22 covers SAML/LDAP/OIDC/proxy/TLS identity boundaries in depth.

8. Token lifetime and rotation design

A token rotation is not complete when a new token exists. It is complete when every dependent consumer has moved to the new credential, the old token is revoked, and a verification proves no unexpected consumer still depends on it.

token inventory fields:
  owner identity
  token type
  project/global scope
  created / expires
  consumers: CI job, IDE, script, service
  secret-store location
  rotation owner
  last verification
  revocation proof

Use the SonarQube-Authentication-Token-Expiration response header where available to detect approaching expiry. Enterprise edition can enforce a maximum lifetime for newly generated tokens; Community Build can still operationalize explicit expiration and rotation policy.

9. Worked decision table

Scenario	Recommended design	Why
One repository CI	Dedicated project/service identity + project Execute Analysis + project-analysis token	Small blast radius
Developer Connected Mode	Personal/limited user identity + user token	Connected Mode requires user token; preserves individual permissions
Read-only reporting script over one private project	Dedicated limited user with Browse + user token	API user token inherits only required Browse
Temporary issue triage delegate	Group/direct project permission with expiry/review; no admin token	Scope the workflow action rather than broadening identity
Central scanner across all projects	Global analysis only when explicitly justified	Global token has instance-wide blast radius

Knowledge check

Why is a user token from a limited service account safer than a user token from a global admin?

When is a direct-user grant reasonable?

Does private visibility prevent a credential with Execute Analysis from scanning?

Why must token rotation inventory consumers first?

Where should you change a group assignment if external provisioning owns it?

Next lesson

Diagnose identity failures without broadening privilege

Lesson 4 engineers the failures that make authorization look mysterious or encourage unsafe admin-token shortcuts.

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.

Version and edition note

Rechecked 2026-09-08. Mandatory exercises target Community Build 26.9.0.129388 and SonarScanner CLI 8.1.0.6389. Current Community Build documentation says permissions are additive across direct grants and group membership; sonar-users receives global Execute Analysis by default on a fresh installation, so the disposable RBAC lab temporarily removes that grant only after preserving it and restores it during cleanup. Project-analysis tokens are encouraged for one-project scanning. User tokens inherit all permissions of their owner and are the recommended bearer credential for Web API operations; project/global analysis token validity depends on the owner retaining the corresponding Execute Analysis permission. Token expiration can be selected by users; enforcing an instance-wide maximum token lifetime for newly generated tokens is Enterprise edition and above. New projects are public by default in current documentation; the lab uses private projects to make Browse/See Source Code boundaries observable. If an external authentication/provisioning method synchronizes users/groups/permissions, manual changes may be unavailable and the external source of truth owns the change. Web API V2 is gradually replacing older endpoints, so write automation must be checked against the current in-instance API documentation.

Version and compatibility note

SonarQube product names, editions, release trains, scanner runtimes, APIs, authentication options, and platform prerequisites can change independently. Re-check the linked SonarSource primary documentation for the exact target release before applying version-sensitive commands or operational guidance outside the disposable course environment.

Identity evidence boundary. Preserve token metadata, owner/type/expiration, permission matrices, Git revision, scanner logs, report-task.txt/ceTaskId, CE result, gate result, and revocation test separately. Never place token values in the evidence packet.

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this address.