LDAP Integration
You can configure SonarQube authentication and authorization to an LDAP server (including LDAP Service of Active Directory) by configuring the correct values in your $SONARQUBE_HOME/conf/sonar.properties file.
The main features are:
Password checking against the external authentication engine.
Automatic synchronization of usernames and emails.
Automatic synchronization of relationships between users and groups (authorization).
Ability to authenticate against both the external and the internal authentication systems. There is an automatic fallback on SonarQube internal system if the LDAP server is down.
During the first authentication trial, if the user's password is correct, the SonarQube database is automatically populated with the new user. Each time a user logs into SonarQube, the username, the email and the groups this user belongs to that are refreshed in the SonarQube database. You can choose to have group membership synchronized as well, but this is not the default.
|
Apache DS |
OpenLDAP |
OpenDS |
Active Directory |
Anonymous |
|
|
|
|
Simple |
|
|
|
|
LDAPS |
|
|
|
|
DIGEST-MD5 |
|
|
|
|
CRAM-MD5 |
|
|
|
|
GSSAPI |
|
|
|
|
- means that it has been successfully tested
Usage
Configure the LDAP plugin by editing the SONARQUBE_HOME/conf/sonar.properties file (see table below)
Restart the SonarQube server and check the log file for:
INFO org.sonar.INFO Security realm: LDAP ...
INFO o.s.p.l.LdapContextFactory Test LDAP connection: OK
Log into SonarQube
On log out users will be presented login page (/sessions/login), where they can choose to login as technical user or a domain user by passing appropriate credentials
From SonarQube Scanners, we recommend using local technical users for authentication against SonarQube Server .
General Configuration
These properties are already present, though commented out, in your sonar.properties file.
Property |
Description |
Default value |
Mandatory |
Example |
sonar.security.realm |
To first try to authenticate against the external sytem. If the external system is not reachable or if the user is not defined in the external system, the authentication will be performed through the SonarQube internal system. |
None |
Yes |
LDAP (only possible value) |
sonar.authenticator.downcase |
Set to true when connecting to a LDAP server using a case-insensitive setup. |
false |
No |
|
ldap.url |
URL of the LDAP server. Note that if you are using ldaps, then you should install the server certificate into the Java truststore. |
None |
Yes |
ldap://localhost:10389 |
ldap.bindDn |
Bind DN is the username of an LDAP user to connect (or bind) with. Leave this blank for anonymous access to the LDAP directory. |
None |
No |
cn=sonar,ou=users,o=mycompany |
ldap.bindPassword |
Bind Password is the password of the user to connect with. Leave this blank for anonymous access to the LDAP directory. |
None |
No |
secret |
ldap.authentication |
Possible values: simple | CRAM-MD5 | DIGEST-MD5 | GSSAPI See http://java.sun.com/products/jndi/tutorial/ldap/security/auth.html |
simple |
No |
|
ldap.realm |
See http://java.sun.com/products/jndi/tutorial/ldap/security/digest.html |
None |
No |
example.org |
ldap.contextFactoryClass |
Context factory class. |
com.sun.jndi.ldap.LdapCtxFactory |
No |
|
ldap.StartTLS |
Enable usage of StartTLS Available since version 2.1. |
false |
No |
|
ldap.followReferrals |
Follow or not referrals. See http://docs.oracle.com/javase/jndi/tutorial/ldap/referral/jndi.html Available since version 2.2. |
true |
No |
|
User Mapping
Property |
Description |
Default value |
Mandatory |
Example for Active Directory Server |
ldap.user.baseDn |
Distinguished Name (DN) of the root node in LDAP from which to search for users. |
None |
Yes |
cn=users,dc=example,dc=org |
ldap.user.request |
LDAP user request. Available since version 1.2. |
(&(objectClass=inetOrgPerson)(uid={login})) |
No |
(&(objectClass=user)(sAMAccountName={login})) |
ldap.user.realNameAttribute |
Attribute in LDAP defining the user’s real name. |
cn |
No |
|
ldap.user.emailAttribute |
Attribute in LDAP defining the user’s email. |
|
No |
|
Group Mapping
Only groups are supported (not roles). Only static groups are supported (not dynamic groups).
When group mapping is configured (i.e the below ldap.group.* properties are configured), membership in LDAP server will override any membership locally configured in SonarQube. LDAP server becomes the one and only place to manage group membership (and the info is fetched each time the user logs in).
For the delegation of authorization, groups must be first defined in SonarQube. Then, the following properties must be defined to allow SonarQube to automatically synchronize the relationships between users and groups.
Property |
Description |
Default value |
Mandatory |
Example for Active Directory Server |
ldap.group.baseDn |
Distinguished Name (DN) of the root node in LDAP from which to search for groups. |
None |
No |
cn=groups,dc=example,dc=org |
ldap.group.request |
LDAP group request. Available since version 1.2. |
(&(objectClass=groupOfUniqueNames)(uniqueMember={dn})) |
No |
(&(objectClass=group)(member={dn})) |
ldap.group.idAttribute |
Property used to specifiy the attribute to be used for returning the list of user groups in the compatibility mode. |
cn |
No |
sAMAccountName |
Configuration Examples
Example of LDAP Configuration
# LDAP configuration
# General Configuration
sonar.security.realm=LDAP
ldap.url=ldap:
//myserver
.mycompany.com
ldap.bindDn=my_bind_dn
ldap.bindPassword=my_bind_password
# User Configuration
ldap.user.baseDn=ou=Users,
dc
=mycompany,
dc
=com
ldap.user.request=(&(objectClass=inetOrgPerson)(uid={login}))
ldap.user.realNameAttribute=cn
ldap.user.emailAttribute=mail
# Group Configuration
ldap.group.baseDn=ou=Groups,
dc
=sonarsource,
dc
=com
ldap.group.request=(&(objectClass=posixGroup)(memberUid={uid}))
Advanced Topics
See the Advanced Topics sub-page for authentication methods, multiple servers and troubleshooting tips.