Set up enterprise user authentication for SonarQube using LDAP and Active Directory. Configure group mapping, role-based access control, and automated user provisioning for centralized identity management.
Prerequisites
- SonarQube server installed and running
- Active Directory server access
- Network connectivity between SonarQube and AD
- Service account credentials for LDAP binding
- Administrative access to SonarQube
What this solves
SonarQube LDAP authentication integrates your code quality platform with Active Directory or other LDAP servers, enabling centralized user management and single sign-on capabilities. This eliminates the need to manage separate SonarQube user accounts and automatically provisions users based on their directory group memberships.
Step-by-step configuration
Install LDAP client libraries
Install the necessary LDAP client libraries and dependencies that SonarQube requires for directory authentication.
sudo apt update
sudo apt install -y ldap-utils libldap-2.5-0 libldap-commonTest LDAP connectivity
Verify that your server can connect to the Active Directory server before configuring SonarQube.
ldapsearch -x -H ldap://dc.example.com:389 -D "CN=sonar-bind,OU=Service Accounts,DC=example,DC=com" -W -b "DC=example,DC=com" "(sAMAccountName=testuser)" cn mailStop SonarQube service
Stop the SonarQube service to safely modify its configuration files.
sudo systemctl stop sonarqubeConfigure LDAP connection properties
Edit the SonarQube configuration file to add LDAP authentication settings. This configures the connection to your Active Directory server.
# Enable LDAP authentication
sonar.security.realm=LDAP
sonar.authenticator.downcase=true
LDAP connection settings
ldap.url=ldap://dc.example.com:389
ldap.bindDn=CN=sonar-bind,OU=Service Accounts,DC=example,DC=com
ldap.bindPassword=SecureBindPassword123!
User configuration
ldap.user.baseDn=OU=Users,DC=example,DC=com
ldap.user.request=(&(objectClass=user)(sAMAccountName={login}))
ldap.user.realNameAttribute=displayName
ldap.user.emailAttribute=mail
Group configuration
ldap.group.baseDn=OU=Groups,DC=example,DC=com
ldap.group.request=(&(objectClass=group)(member={dn}))
ldap.group.idAttribute=cnConfigure group mapping and permissions
Add group mapping configuration to automatically assign SonarQube roles based on Active Directory group membership.
# Group mapping for role assignment
ldap.group.request=(&(objectClass=group)(member={dn}))
ldap.group.idAttribute=cn
Enable group synchronization
sonar.security.localUsers=admin
Security settings
sonar.forceAuthentication=true
sonar.security.updateUserAttributes=trueSet proper file ownership
Ensure the SonarQube user can read the configuration file with the LDAP credentials.
sudo chown sonarqube:sonarqube /opt/sonarqube/conf/sonar.properties
sudo chmod 640 /opt/sonarqube/conf/sonar.propertiesConfigure SSL/TLS for secure LDAP
If using LDAPS (LDAP over SSL), add SSL configuration to encrypt authentication traffic.
# For LDAPS (SSL/TLS)
ldap.url=ldaps://dc.example.com:636
SSL certificate verification (optional)
ldap.StartTLS=true
ldap.truststore=/path/to/truststore.jks
ldap.truststorePassword=truststore_password
Start SonarQube and verify startup
Start the SonarQube service and check that it starts successfully with LDAP authentication enabled.
sudo systemctl start sonarqube
sudo systemctl status sonarqube
Check logs for LDAP initialization
sudo tail -f /opt/sonarqube/logs/sonar.logConfigure role-based access control
Access the SonarQube web interface and configure group permissions. Log in as the admin user first.
http://your-sonarqube-server:9000
Login with local admin account initially
Username: admin
Password: admin (change immediately)
Set up automatic group synchronization
Configure SonarQube to automatically create and assign permissions based on Active Directory groups through the web interface.
- Navigate to Administration → Security → Groups
- Create groups matching your AD groups (e.g., "SonarQube-Developers", "SonarQube-Admins")
- Assign appropriate permissions to each group
- Users will automatically be added to groups based on their AD membership
Verify your setup
Test the LDAP authentication configuration and verify user login functionality.
# Check SonarQube service status
sudo systemctl status sonarqube
Test LDAP connectivity from SonarQube server
ldapsearch -x -H ldap://dc.example.com:389 -D "CN=sonar-bind,OU=Service Accounts,DC=example,DC=com" -W -b "OU=Users,DC=example,DC=com" "(sAMAccountName=testuser)" cn displayName mail
Check SonarQube logs for LDAP messages
sudo grep -i ldap /opt/sonarqube/logs/sonar.log
Verify web interface accessibility
curl -I http://localhost:9000Test user authentication by logging out of the admin account and attempting to log in with an Active Directory user account. The user should be authenticated successfully and automatically assigned to appropriate groups based on their AD membership.
Advanced configuration options
Multiple LDAP servers for high availability
Configure multiple LDAP servers for failover support.
# Multiple LDAP servers
ldap.url=ldap://dc1.example.com:389,ldap://dc2.example.com:389User attribute mapping
Customize which Active Directory attributes map to SonarQube user properties.
# Custom attribute mapping
ldap.user.realNameAttribute=displayName
ldap.user.emailAttribute=mail
ldap.user.request=(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(|(sAMAccountName={login})(userPrincipalName={login})))Common issues
| Symptom | Cause | Fix |
|---|---|---|
| "LDAP connection failed" | Network connectivity or wrong server address | Test with ldapsearch and verify firewall rules |
| "Authentication failed" for valid users | Incorrect bind DN or user search base | Verify DN format matches your AD structure |
| Users can login but have no permissions | Group mapping not configured | Create SonarQube groups and assign permissions |
| "SSL/TLS handshake failed" | Certificate trust issues with LDAPS | Import AD certificate or configure truststore |
| Service fails to start after LDAP config | Syntax error in sonar.properties | Check logs and validate configuration syntax |
| Local admin locked out | LDAP misconfiguration | Add sonar.security.localUsers=admin and restart |
Security best practices
Secure the bind account
Create a dedicated service account for SonarQube LDAP binding with minimal required permissions.
- Grant only "Read" permissions on the user and group OUs
- Use a strong, complex password
- Consider using a managed service account (MSA) if available
- Regularly rotate the bind account password
Enable audit logging
Configure SonarQube to log authentication events for security monitoring.
# Enable authentication logging
sonar.log.level.web=DEBUG
sonar.log.level.org.sonar.server.authentication=DEBUGFor production deployments, consider implementing NGINX reverse proxy with SSL termination to secure web traffic, and integrate with centralized logging systems for comprehensive security monitoring.
Next steps
- Install and configure SonarQube with PostgreSQL and SSL
- Configure SonarQube quality gates and automated project analysis
- Integrate SonarQube with Jenkins CI/CD pipeline for automated code quality checks
- Set up SonarQube high availability cluster with PostgreSQL replication
- Configure SonarQube webhook notifications for Slack and Microsoft Teams