Configure SonarQube LDAP authentication with Active Directory and user group management

Intermediate 25 min Apr 14, 2026 200 views
Ubuntu 24.04 Debian 12 AlmaLinux 9 Rocky Linux 9

Set up SonarQube to authenticate users against Active Directory using LDAP. Configure automatic user provisioning, group synchronization, and role-based access control for enterprise environments with centralized authentication.

Prerequisites

  • SonarQube 9.x or higher installed
  • Active Directory server accessible
  • LDAP service account with read permissions
  • Administrator access to SonarQube

What this solves

SonarQube LDAP authentication integrates your code quality platform with Active Directory, eliminating the need for separate user accounts. This enables centralized user management, automatic group synchronization, and role-based access control based on AD group memberships.

Prerequisites and requirements

Before configuring LDAP authentication, ensure you have the following information from your Active Directory administrator:

  • LDAP server URL and port (typically 389 for LDAP, 636 for LDAPS)
  • Service account credentials for LDAP binding
  • Base DN for users and groups
  • Group distinguished names for SonarQube permissions
Note: This tutorial assumes you have SonarQube already installed and running. If you need to install SonarQube first, see our SonarQube installation guide.

Step-by-step configuration

Stop SonarQube service

Stop SonarQube before making configuration changes to ensure settings are properly loaded.

sudo systemctl stop sonarqube

Configure LDAP connection settings

Edit the SonarQube configuration file to add LDAP server connection parameters.

# Enable LDAP authentication
sonar.security.realm=LDAP

LDAP server configuration

ldap.url=ldap://ad.example.com:389 ldap.bindDn=CN=sonarqube-svc,OU=Service Accounts,DC=example,DC=com ldap.bindPassword=YourServiceAccountPassword

Connection settings

ldap.authentication=simple ldap.followReferrals=true ldap.connectTimeout=5000 ldap.responseTimeout=10000

Configure user authentication mapping

Define how SonarQube maps LDAP user attributes to internal user properties.

# 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

Optional: Map additional user attributes

ldap.user.firstNameAttribute=givenName ldap.user.lastNameAttribute=sn

Configure group mapping and synchronization

Set up automatic group synchronization to map Active Directory groups to SonarQube permissions.

# Group configuration
ldap.group.baseDn=OU=Groups,DC=example,DC=com
ldap.group.request=(&(objectClass=group)(member={dn}))
ldap.group.idAttribute=sAMAccountName

Group mapping for role-based access

sonar.security.localUsers=admin

Map specific AD groups to SonarQube groups

ldap.group.mapping.administrators=CN=SonarQube-Admins,OU=Groups,DC=example,DC=com ldap.group.mapping.users=CN=SonarQube-Users,OU=Groups,DC=example,DC=com ldap.group.mapping.developers=CN=Development-Team,OU=Groups,DC=example,DC=com

Configure SSL encryption for LDAPS

For production environments, configure SSL/TLS encryption for secure LDAP communication.

# LDAPS configuration (recommended for production)
ldap.url=ldaps://ad.example.com:636

SSL certificate validation

ldap.StartTLS=false

Trust store configuration (if using custom certificates)

sonar.web.javaOpts=-Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=password

Set file ownership and permissions

Ensure the SonarQube user can read the configuration file while keeping sensitive credentials secure.

sudo chown sonarqube:sonarqube /opt/sonarqube/conf/sonar.properties
sudo chmod 640 /opt/sonarqube/conf/sonar.properties
Never use chmod 777. It gives every user on the system full access to your files, including LDAP passwords. Instead, use specific ownership and minimal permissions.

Start SonarQube and verify configuration

Start the service and monitor logs for any LDAP connection issues.

sudo systemctl start sonarqube
sudo systemctl status sonarqube
sudo tail -f /opt/sonarqube/logs/sonar.log

Configure role-based access control

Access SonarQube web interface

Log into SonarQube using the admin account to configure group permissions.

https://sonarqube.example.com:9000

Configure group permissions

Navigate to Administration > Security > Global Permissions to assign permissions to LDAP groups.

GroupPermissionsPurpose
SonarQube-AdminsAdminister System, Administer Quality GatesFull administrative access
Development-TeamBrowse, Create Projects, Provision ProjectsDevelopers can create and analyze projects
SonarQube-UsersBrowseRead-only access to view analysis results

Test LDAP authentication

Test login with an Active Directory account to verify LDAP integration.

  • Log out of the admin account
  • Attempt login with an AD username and password
  • Verify user profile shows correct name and email from LDAP
  • Check that group memberships are correctly synchronized

Advanced LDAP configuration

Configure multiple LDAP servers

For high availability, configure multiple domain controllers for failover.

# Multiple LDAP servers for redundancy
ldap.url=ldap://dc1.example.com:389 ldap://dc2.example.com:389

Connection pooling

ldap.connectionPooling=true

Configure nested group support

Enable nested group resolution for complex Active Directory structures.

# Nested groups configuration
ldap.group.request=(&(objectClass=group)(|(member={dn})(member:1.2.840.113556.1.4.1941:={dn})))

Configure user synchronization scheduling

Set up automatic user and group synchronization intervals.

# Synchronization settings
sonar.security.ldap.sync.userGroups=true
sonar.security.ldap.sync.interval=3600

Verify your setup

Confirm LDAP authentication is working correctly with these verification steps:

# Check SonarQube is running and responding
curl -I http://localhost:9000

Verify LDAP connectivity from SonarQube server

ldapsearch -x -H ldap://ad.example.com:389 -D "CN=sonarqube-svc,OU=Service Accounts,DC=example,DC=com" -w "password" -b "DC=example,DC=com" "(objectClass=user)" | head -20

Check SonarQube logs for LDAP authentication attempts

sudo tail -50 /opt/sonarqube/logs/sonar.log | grep -i ldap
Note: For comprehensive monitoring of your SonarQube instance, consider implementing our SonarQube monitoring and quality gates configuration.

Common issues

SymptomCauseFix
LDAP bind failedIncorrect service account credentialsVerify ldap.bindDn and ldap.bindPassword with AD admin
Users not foundWrong user base DN or search filterTest LDAP search manually: ldapsearch -x -H ldap://server -D binddn -w pass -b userdn
Groups not synchronizedGroup mapping configuration errorCheck ldap.group.baseDn and verify group membership in AD
SSL connection failedCertificate validation issuesImport AD certificate to Java truststore or configure custom truststore
Slow authenticationNetwork latency or large directoryTune ldap.connectTimeout and ldap.responseTimeout values
Permission denied on configWrong file ownershipsudo chown sonarqube:sonarqube /opt/sonarqube/conf/sonar.properties

Next steps

Automated install script

Run this to automate the entire setup

Need help?

Don't want to manage this yourself?

We handle infrastructure security hardening for businesses that depend on uptime. From initial setup to ongoing operations.