SonarQube Administration Users and Permissions
SonarQube provides a complete access control system that lets administrators control exactly who can see which projects, who can change settings, and who can run scans. This topic explains how to manage users, groups, and permissions at both the global and project level.
Two Levels of Permissions
GLOBAL PERMISSIONS PROJECT PERMISSIONS -------------------------- ------------------------- Apply to the entire server Apply to one specific project Managed under Administration Managed in Project Settings Examples: Examples: - Create projects - View results - Manage quality profiles - See source code - Administer all settings - Run analysis - Administer users/groups - Manage issues
The Admin Account
The admin account created during installation has full access to everything. Change its default password immediately after installation. Do not use the admin account for daily developer tasks — create individual accounts for each team member instead.
User Authentication Modes
AUTH MODE HOW IT WORKS -------------- ----------------------------------------------- Local accounts Users created directly in SonarQube LDAP Connects to your company's Active Directory SAML Single sign-on (SSO) via Google, Okta, Azure AD GitHub OAuth Login with GitHub credentials GitLab OAuth Login with GitLab credentials
SAML and OAuth integrations are configured in Administration > Configuration > Security. After setup, users log in with their existing corporate credentials instead of creating a separate SonarQube password.
Creating a Local User
- Go to Administration > Security > Users
- Click Create User
- Enter a login name, display name, email address, and temporary password
- Click Create
The user receives a notification email if email is configured. On first login, SonarQube prompts them to set a new password.
CREATE USER FORM +--------------------------------------------+ | Login: jsmith | | Name: John Smith | | Email: jsmith@company.com | | Password: [temporary — user will reset] | +--------------------------------------------+
User Groups
Groups make permission management much easier in large teams. Instead of assigning permissions to each user individually, you add users to a group and assign permissions to the group once.
WITHOUT GROUPS (tedious) WITH GROUPS (efficient) User A: set 6 permissions Group: Backend Team User B: set 6 permissions Users: A, B, C, D, E User C: set 6 permissions Permissions: 6 permissions set once User D: set 6 permissions User E: set 6 permissions New user F? Add to group — done.
Creating a Group
- Go to Administration > Security > Groups
- Click Create Group
- Enter a name (e.g.,
backend-developers) and description - Click Create
- Click Members next to the group to add users
Global Permission Types
GLOBAL PERMISSION WHO NEEDS IT ----------------------- -------------------------------- Administer System Platform administrators only Create Projects Team leads and DevOps engineers Administer Quality Gates Architects and quality leads Administer Quality Prof. Architects and quality leads Execute Analysis CI/CD service accounts
Grant global permissions at Administration > Security > Global Permissions. Assign to groups rather than individual users whenever possible.
Project Permission Types
PROJECT PERMISSION WHAT IT ALLOWS ------------------- ----------------------------------------- Browse View issues, metrics, and project dashboard See Source Code Read the actual code in the Code tab Administer Issues Change issue status, assignee, and comments Execute Analysis Trigger a scan (used by CI tokens) Administer Project Change project settings, profiles, gate
Assigning Project Permissions
Go to Project Settings > Permissions inside any project. You can grant permissions to individual users or to groups. The most common pattern for a team:
PROJECT PERMISSIONS SETUP +-----------------------------------------------+ | GROUP: developers | | [x] Browse | | [x] See Source Code | | [x] Administer Issues | | [ ] Execute Analysis | | [ ] Administer Project | | | | GROUP: ci-accounts | | [ ] Browse | | [ ] See Source Code | | [ ] Administer Issues | | [x] Execute Analysis | | [ ] Administer Project | | | | GROUP: team-leads | | [x] Browse | | [x] See Source Code | | [x] Administer Issues | | [x] Execute Analysis | | [x] Administer Project | +-----------------------------------------------+
Service Accounts for CI/CD
Create a dedicated SonarQube user for each CI/CD system (e.g., jenkins-ci, github-actions-ci). Generate tokens for these accounts and use them in pipeline configurations. This approach gives you fine-grained control — you can revoke a CI token without affecting any human user accounts.
SERVICE ACCOUNT SETUP
1. Create user: jenkins-ci (local account)
2. Add jenkins-ci to group: ci-accounts
3. Grant ci-accounts the Execute Analysis permission
on all relevant projects
4. Generate a token for jenkins-ci
5. Use that token in Jenkinsfile credentials
Token Management
Tokens are the secure alternative to passwords for scanner authentication. Each user can generate multiple tokens with different names. Administrators can see all tokens and revoke any token from Administration > Security > Users by clicking the token count for a user.
TOKEN BEST PRACTICES - One token per CI/CD system or environment - Name tokens descriptively: "jenkins-prod", "github-staging" - Rotate tokens every 90 days for high-security environments - Revoke tokens immediately when a team member leaves - Never share tokens between team members
Project Visibility: Public vs Private
Project visibility controls whether logged-out users or users without explicit permissions can see a project. Set project visibility in Project Settings > Permissions:
- Public: Anyone who can access the SonarQube server URL can browse the project
- Private: Only users with the Browse permission can see the project
Change the default visibility for new projects at Administration > Projects > Management > Default visibility. Set this to Private for most organizations.
Auditing User Activity
SonarQube logs significant administrative actions in its audit log. Access it at Administration > Audit Logs. The log records who changed which setting and when. This is important for compliance in regulated industries where changes to security configuration must be traceable.
AUDIT LOG SAMPLE +----------------------------------------------+ | 2024-03-15 14:22:01 | admin | | | Changed Quality Gate "Sonar Way" conditions| | | | 2024-03-15 09:11:44 | jsmith | | | Marked issue #4521 as Won't Fix | | | | 2024-03-14 16:05:30 | jenkins-ci | | | Executed analysis on project: api-service | +----------------------------------------------+
Resetting a Forgotten Admin Password
If the admin password is lost and no other admin account exists, reset it using the SonarQube reset script on the server:
# Linux — run from the SonarQube directory
java -jar lib/sonar-application-*.jar \
-Dsonar.security.realm= \
-Dsonar.web.javaAdditionalOpts="-Dsonar.resetPassword=true"
This flag temporarily bypasses authentication and lets you set a new admin password from the web interface. Remove the flag and restart SonarQube immediately after resetting the password.