LDAP Integration
LDAP integration in TeamCity has two levels: authentication (login) and synchronization.
Authentication
If you need to limit the users who can log into TeamCity to LDAP users, you need to set LDAP authentication module in main-config.xml
file and configure LDAP connection settings in ldap-config.properties
file. Refer to Authentication Settings page for details.
main-config.xml Configuration
Configure login-module
settings of <TeamCity data directory> /config/main-config.xml
as follows:
<auth-type> <login-module class="jetbrains.buildServer.serverSide.impl.auth.LDAPLoginModule" /> <!-- Welcome message displayed to users on login form --> <login-description>Welcome to TeamCity, your team building environment!</login-description> <!-- Whether anonymous "view-only" logins are supported --> <guest-login allowed="true" /> </auth-type>
On each user login, authentication is performed by direct login into LDAP with the credentials entered in the login form. TeamCity does not store the user passwords in this case.
TeamCity stores user details and settings in its own database. Refer to Synchronization section below for information on ability to retrieve common user properties from LDAP.
ldap-config.properties Configuration
LDAP connection settings are configured in ldap-config.properties
file residing in <TeamCity data directory> /config
. Since TeamCity 4.5 you can find ldap-config.properties.dist
file containing configuration options description. Do not edit ldap-config.properties.dist
directly, copy it to ldap-config.properties
before editing; (the .dist
file will be overwritten with the default content on each server start).
Since TeamCity 4.5 ldap-config.properties
file is re-read on any modification so you do not need to restart the server to apply changes in the file. Please make sure you always back up previous version of the file: if you misconfigure LDAP integration, you may no longer be able to log in into TeamCity. Already logged-in users are not affected by the modified LDAP integration settings because users are authenticated only on login.
The mandatory property in ldap-config.properties
file is java.naming.provider.url
that configures the server and root DN. The property stores URL to the LDAP server node that is used in following LDAP queries. e.g. ldap://dc.example.com:389/CN=Users,DC=Example,DC=Com
. Please note that the value of the property should use URL-escaping if necessary. e.g. use %20
if you need space character.
Configuring User Login
You might want to configure the integration so that users enter only the username in TeamCity login form, but LDAP server can require prefixes or suffixes to the name. This can be addressed with teamcity.auth.formatDN
property (Since TeamCity 4.5, previous versions require "formatDN
" as the property name). The property defines the transformation that is applied to the entered username before the LDAP login is tried. The property should reference the entered username as $login$
. Note that TeamCity store the username for the user in unmodified form as entered by the user. This is necessary to allow mapping of LDAP user back to TeamCity user, refer to the teamcity.users.username
property description below.
Example:
teamcity.auth.formatDN=uid=$login$,ou=people,dc=company,dc=com
Some LDAP servers support multiple formats of username. Usually, you would want to restrict the users from entering different variations of the username (otherwise, a new TeamCity user will be created for each variation). The restriction can be configured via the help of teamcity.auth.loginFilter
property (Since TeamCity 4.5, previous versions require "loginFilter
" as the name of the property). The property configures regular expression that entered username should comply to.
Example (allow any username):
teamcity.auth.loginFilter=.+
By default, login format is restricted to a name without "\", "/" and "@" characters. This format applies only Since TeamCity 4.5, in previous versions the pattern is to match DOMAIN\name
patterns.
By default, TeamCity stores the entered login as the username in database. This value is important if you want to synchronize user information, e.g. display name or e-mail, with LDAP data (see the details below). That's why it can be useful to configure the login filter so that user may login with the username stored in LDAP only.
If LDAP server accepts several variations of the login name and they cannot be filtered by teamcity.auth.loginFilter
(or it is undesirable to limit the login names to particular format), TeamCity provides ability to automatically fetch the username from LDAP. If teamcity.users.acceptedLogin
property is configured, it will be used to find a user by the entered login name in LDAP and then the user will be stored/matched in TeamCity database with the username that will be retrieved from the attribute defined by teamcity.users.username
property.
This logic is automatically turned on if teamcity.users.acceptedLogin
property is defined. In this case teamcity.users.base
(root DN for users serach) and teamcity.users.username
are mandatory.
Also, you can define a teamcity.users.login.filter
property with a filter to apply when searching for a user in LDAP. The property may have a $login$
substring that will be substituted with the actual login name entered by the user on TeamCity login form.
Provided these options are configured, on each login attempt TeamCity will perform a look-up in LDAP searching for the entered login and retrieve the username.
Please note that in certain configurations (for example, with java.naming.security.authentication=simple
) login information will be sent to the LDAP server in not-encrypted form. For securing the connection you can refer to corresponding Sun documentation. Another option is to configure communications via ldaps protocol.
Related external link: How To Set Up Secure LDAP Authentication with TeamCity by Alexander Groß.
Active Directory
The following template enables authentication against active directory:
Add the following code to the < >/config/ldap-config.properties
file (assuming the domain name is "Example.Com
" and domain controller is "dc.example.com
").
java.naming.provider.url=ldap://dc.example.com:389/CN=Users,DC=Example,DC=Com java.naming.security.authentication=simple java.naming.referral=follow
Advanced Configuration
If you need to fine-tune LDAP connection settings, you can add java.naming
options to the ldap-config.properties
file: they will be passed to underlying Java library. Default options are retrieved using java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
. Refer to the http://java.sun.com/products/jndi/tutorial/ldap/security/ldap.html page for more information about property names and values.
You can use an LDAP explorer to browse LDAP directory and verify the settings (for example, http://www.jxplorer.org/).
There is an ability to specify multiple servers using the pattern:
java.naming.provider.url=ldap://ldap.mycompany.com:389 ldap://ldap2.mycompany.com:389 ldap://ldap3.mycompany.com:389
Synchronization
LDAP synchronization is only available since TeamCity 4.5.
LDAP synchronization allows to:
Retrieve user's profile data from LDAP
Update user groups membership based on LDAP groups
Automatically create and remove users in TeamCity based on information retrieved from LDAP
Periodically, TeamCity fetches data from LDAP and updates users in TeamCity. You can review the last synchronization run statistics and schedule new synchronization in LDAP Synchronization section of Configuring the Server.
Common Configuration
You need to have LDAP authentication configured for the synchronization to function.
By default, the synchronization is turned off. To turn it on, add the following option to ldap-config.properties
file:
teamcity.options.users.synchronize=true
You also need to specify the following mandatory properties: java.naming.security.principal
and java.naming.security.credentials
(they specify user credentials which are used by TeamCity to connect to LDAP and retrieve data), teamcity.users.base
and teamcity.users.filter
(specify the settings to search for users), and teamcity.users.username
(the name of LDAP attribute containing the username).
TeamCity should be able to fetch users from LDAP and map them to the existing TeamCity users. Mapping between the LDAP user and TeamCity user is configured by teamcity.users.username
property.
Example:
teamcity.users.username=sAMAccountName
User Profile Data
When properly configured, TeamCity can retrieve user-related information from LDAP (e-mail, full name, or any custom property) and store it as TeamCity user's details. If updated in LDAP, the data will be updated in TeamCity user's profile. If modified in user's profile in TeamCity, the data will no longer be updated from LDAP for the modified fields.
The user's profile synchronization is performed on user creation and also periodically for all users.
All the user fields synchronization properties store the name of LDAP field to retrieve the information from.
The list of supported user settings:
teamcity.users.username
teamcity.users.property.displayName
teamcity.users.property.email
teamcity.users.property.plugin:notificator:jabber:jabber-account
teamcity.users.property.plugin:vcs:<VCS type>:anyVcsRoot
— VCS username for all <VCS type> roots. The following VCS types are supported: svn, perforce, cvs, tfs, vss, clearcase, starteam
User Group Membership
TeamCity can automatically update users membership in groups based on the LDAP-provided data. You will need to create groups in TeamCity manually and then specify the mapping on LDAP groups in <TeamCity data directory> /config/ldap-mapping.xml
file. You can find ldap-mapping.xml.dist
file describing the layout. Do not edit ldap-mapping.xml.dist
directly, copy it to ldap-mapping.xml
before editing (the .dist
file will be overwritten with the default content on each server start).
In the file you will need to specify correspondence between TeamCity user group (determined by group id) and LDAP group (specified by group DN). Also you need to set the following properties: teamcity.options.groups.synchronize
(enables user group synchronization), teamcity.groups.base
and teamcity.groups.filter
(specify where and how to find the groups in LDAP) and teamcity.groups.property.member
(specifies the LDAP attribute holding the members of the group).
On each synchronization run, TeamCity updates the membership of users in groups that are configured in the mapping.
If either LDAP group or TeamCity that is configured in the mapping is not found, an error is reported. You can review the errors occurred during last synchronization run in "LDAP Synchronization" section of Configuring the Server.
Creating and Deleting User
TeamCity can automatically create users in TeamCity, if they are found in one of the mapped LDAP groups.
By default, automatic user creation is turned off. To turn it on, set teamcity.options.createUsers
property to true
in ldap-config.properties
file.
TeamCity can automatically delete users in TeamCity if they cannot be found in LDAP or do not belong to an LDAP group that is mapped to predefined "All Users" group. By default, automatic user deletion is turned off as well; set teamcity.options.deleteUsers
property to turn it on.
Username migration
The username for the existing users can be updated upon first successful login. For instance, suppose the user had previously logged in using 'DOMAIN\user' name, thus the string 'DOMAIN\user' had been stored in TeamCity as the username. In order to synchronize the data with LDAP user can change the username to 'user' using the following options:
teamcity.users.login.capture=DOMAIN\\\\(.*) teamcity.users.login.filter=(cn=$login$) teamcity.users.previousUsername=DOMAIN\\\\$login$
The first property allows you to capture the username from the input login and use it to authenticate the user (can be particularly useful when the domain 'DOMAIN' isn't stored anywhere in LDAP). The second property teamcity.users.login.filter
allows you to fetch the username from LDAP by specifying the search filter to find this user (other mandatory properties to use this feature: teamcity.users.base
and teamcity.users.username
). The third property allows to find the 'DOMAIN\user' username when login with just 'user', and replace it with either captured login, or with the username from LDAP.
Note that if any of these properties are not set, or cannot be applied, the username isn't changed (the input login name is used).
Debugging LDAP Integration
You can get detailed logs of LDAP login and synchronize processes by uncommenting LDAP-related lines in Logs of Internal Events. The logs go into "logs/teamcity-ldap.log"
file.