Users, Groups, Permissions, Tokens, Authentication, and Authorization: Diagnostics, Failure Modes, and Production Practices

1. Evidence-first diagnostic sequence

1. Preserve the first scanner/API/CI response and exact timestamp.
2. Record SonarQube Community Build/Server version, edition, instance mode, scanner/runtime, and relevant integration version.
3. Confirm the exact identity/token owner and token type without logging the token value.
4. Confirm source revision, project key, effective scanner parameters, and report-task.txt/ceTaskId if upload occurred.
5. Inspect group memberships, direct grants, global permissions, project permissions, template/visibility, and authentication source.
6. Distinguish authentication failure from authorization failure.
7. Inspect dependent CI/IDE/API consumers before any rotation/revocation.
8. Apply the least-destructive correction and repeat the smallest equivalent request at the same revision.

2. Failure: using an administrator token for routine scanners

An admin user token can perform any API/UI action the administrator can perform. Using it as a scanner secret turns a routine build compromise into potential instance administration compromise. Replace it with a project-analysis token owned by an identity that has only project Execute Analysis.

Do not “validate” the repair by merely seeing the scan pass. Prove the narrow credential fails to perform an unrelated administrative action.

3. Failure: committing tokens

If a SonarQube token appears in Git history, treat it as compromised: preserve the incident evidence, revoke it, inventory affected consumers, issue the narrow replacement, and remove/redact the secret from active configuration according to your repository incident process. Do not assume deleting the current file removes the secret from history.

4. Failure: confusing authentication with authorization

Do not “solve” an authorization failure by switching to an administrator token. That masks the layer being diagnosed.

5. Failure: direct-user permission sprawl

A project accumulates direct grants over months. Team membership changes, but old grants remain. The correction is not a mass delete without evidence. Export the current matrix, map each direct grant to an owner/business reason, migrate normal access to groups/templates, preserve approved exceptions, then remove only grants that have been explicitly superseded.

6. Failure: orphaned long-lived tokens

A token with no known consumer or owner is an access path that cannot be governed. Current Community Build allows token expiration selection; use short/appropriate lifetimes and a consumer registry. Monitor the token-expiration HTTP response header for API automation where available.

When a user is deactivated or loses Execute Analysis, analysis tokens tied to that user’s permission can stop working. Preserve the permission-change evidence before rotating tokens blindly.

7. Failure: testing only as admin

Administrator testing proves that the instance works under maximal privilege; it does not prove that team RBAC works. Every access design should include at least one positive test and one negative test using the actual bounded identities.

positive: alpha can analyze alpha
negative: alpha cannot analyze beta
positive: beta can browse beta
negative: beta cannot administer alpha
revocation: revoked alpha token cannot authenticate/analyze

8. Failure: rotating without dependent-job inventory

A safe rotation sequence is inventory → create narrow replacement → update consumers → verify new credential → revoke old credential → verify old credential fails. If you revoke first, you may break unknown jobs. If you never revoke old, you create a second valid attack path.

9. Intentionally broken example: Alpha can analyze Beta

Symptom: You carefully created Alpha/Beta groups and project templates, yet Alpha’s scanner succeeds against Beta.

First evidence: do not change the project key, template, or token. Capture Alpha’s group membership, Beta project permissions, and global permissions. On a fresh Community Build instance you may discover that sonar-users still holds global Execute Analysis.

Least-destructive repair in the disposable lab: preserve the original global grant, remove only global Execute Analysis from sonar-users, repeat the same Alpha→Beta scan at the same Git revision/project key, and confirm denial. Then confirm Alpha→Alpha still succeeds from the project template.

This failure is valuable because the local project permissions were not wrong—the broader global permission was the causal layer.

10. Production anti-patterns to reject

• Do not distribute administrator tokens to scanners, IDEs, or scripts.
• Do not print token values in logs or screenshots.
• Do not disable authentication on production merely to fix access.
• Do not change private projects to public as a troubleshooting shortcut.
• Do not directly edit the SonarQube database/search index to repair authorization.
• Do not delete/recreate a project under another key to escape a permission problem.
• Do not remove logs before preserving first failure.
• Do not mass-remove permissions without mapping effective group/direct grants first.

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.