Configuring Authentication Settings

Out-of-the-box TeamCity supports five Authentication Modules including three credentials authentication modules and two HTTP authentication modules:

• Credentials-Authentication-Modules

  • Default-Authentication

  • Windows-Domain-Authentication

  • LDAP Integration (separate page)

• HTTP-Authentication-Modules

  • Basic-HTTP-Authentication

  • NTLM HTTP Authentication (separate page)

The default authentication includes the Default-Authentication and Basic-HTTP-Authentication modules.

Configuring Authentication Modules

There are two ways you can configure authentication modules used by Teamcity:

• via the Web UI

• By editing <TeamCity data directory> /config/auth-config.xml file

Configuring Authentication Modules Using Web UI

The currently used authentication modules are displayed on the Administration | Authentication page.

Simple Mode

Simple mode (default) allows you to select presets created for the most common use cases. To override the existing authentication settings, use the Load preset... button, select one of the options and Save your changes. The following presets are available:

• Default (default - Accessing Server by HTTP)

• LDAP Integration

• LDAP Integration with NTLM HTTP Authentication

• NTLM HTTP Authentication

Advanced Mode

Use the advanced mode to add / remove authentication modules:

1. Switch to advanced mode with the corresponding link on the Administration | Authentication page.

2. Click Add Module and select a module from the drop-down.

3. Use the properties available for modules by selecting/deselecting checkboxes in the Add Module dialog.

4. Click Apply and Save your changes.

The changes made in the UI will be reflected in the auth-config.xml file.

Configuring Authentication Modules Using auth-config.xml

You only need to use this approach if editing via Web UI is not appropriate (e.g. you need to change the authentication settings before the first TeamCity server start).

To enable an authentication module, edit the <TeamCity data directory> /config/auth-config.xml file on the server machine as follows:

1. Add the <auth-module> tag inside the{{<auth-modules>}} tag inside the{{<auth-config>}} tag.

2. Specify the type attribute for the newly created <auth-module> tag.

The following values are supported for the type attribute (the values are case-insensitive):

• For credentials authentication modules:

  • Default for Default Authentication

  • NT-Domain for Windows Domain Authentication

  • LDAP for LDAP Authentication

• For HTTP authentication modules:

  • HTTP-Basic for Basic HTTP Authentication

  • HTTP-NTLM for NTLM HTTP Authentication

You can also provide some properties for each authentication module depending on the module type. Each property is specified as the <property> tag inside the corresponding <auth-module> tag. Each <property> tag must contain the key attribute with a property key. The property value is specified as the text inside the <property> tag.

Also, TeamCity plugins can provide Custom Authentication Module. The server restart is NOT needed after editing this file. The changes will be reflected in the Web UI.

User Authentication Settings

TeamCity administrator specifies authentication settings for users on their profile page.

Since version 8.0, TeamCity maintains a common user list shared among all the authentication modules. This means that users and their settings remain the same after changing TeamCity server authentication modules if their usernames are the same in the old and new authentication modules. But a user can now have different TeamCity username, LDAP username and Windows domain username.The administrator has to specify the user's LDAP/NT username on his/her profile page to make the user be able to login via LDAP/NT authentication. By default, the TeamCity username is equal to LDAP and Windows domain usernames.

When a user attempts to log in, TeamCity will try all the configured modules one by one. If one of them authenticates the user, the login will be successful; if all of them fail, the user will not be able to log into TeamCity.

The very first time TeamCity server starts with no users (and no administrator) so you will be prompted for the administrator account. If you are not prompted for the administrator account, please refer to How To... for a resolution.

There can also be a case when the administrator cannot login after changing authentication modules.

Let's imagine that the administrator had the "jsmith" TeamCity username and used the default authentication. Then the authentication module was changed to Windows domain authentication (i.e. Windows domain authentication module was added and the default one was removed). If, for example, the Windows domain username of that administrator is "john.smith", he/she is not able to login anymore: he/she cannot login using the default authentication since it is disabled, and cannot login using Windows domain authentication since his/her Windows domain username is not equal to TeamCity username. The solution nevertheless is quite simple: the administrator can login using the Super User and change his/her TeamCity username or specify his/her Windows domain username on his/her own profile page.

Example of the relevant auth-config.xml file section:

Credentials Authentication Modules

Built-in Authentication

Users and their passwords are maintained by TeamCity. New users are added by the TeamCity administrator (in the Administration area on the Users page) or users are self-registered if the <property key="freeRegistrationAllowed">true</property> property is set. All newly created users belong to the User Group group and have all roles assigned to this group. If some specific Role and Permission are needed for the newly registered users, these roles should Managing Roles via the All Users group.

Configuration of <TeamCity data directory>/config/auth-config.xml:

Windows Domain Authentication

See also the NTLM HTTP Authentication page for information on single sign-on based on Windows domain authentication (transparent login without entering credentials manually).

Configuration of <TeamCity data directory> /config/auth-config.xml:

To log into TeamCity, users should provide their user name in the DOMAIN\user.name form and their domain password. The <username>@<domain> login name syntax is also supported.

It is also possible to log in using only a username if the domain is specified in the "<property key="defaultDomain">YourDomain</property>" property tag (see above).

Since TeamCity 7.1, when running under Windows, the TeamCity server uses Waffle library for authentication by default. Under Linux, JCIFS library is used for the Windows domain login.

If the allowCreatingNewUsersByLogin property is set to true, a new user account will be created on the first successful login. All newly created users belong to the User Group group and have all roles assigned to this group. If some specific Role and Permission are needed for the newly registered users, these roles should Managing Roles via the All Users group.

The following settings in the <TeamCity data directory> /config/ntlm-config.properties file are obsolete and are not recommended for usage. Please comment them out and report any issues that you have with the configuration.

# ntlm.compatibilityMode=true # teamcity.ntlm.use.jcifs=true

The following settings in <TeamCity data directory> /config/ntlm-config.properties have no effect anymore and should be removed:

ntlm.defaultDomain=domain

jCIFS Library Specific Configuration

The library is configured using the properties specified in the <TeamCity data directory>/config/ntlm-config.properties file. Changes to the file take effect immediately without server restart.

If the default settings do not work for your environment, refer to http://jcifs.samba.org/src/docs/api/ for all available configuration properties. If the library does not find the domain controller to authenticate against, consider adding the jcifs.netbios.wins property to the ntlm-config.properties file with the address of your WINS server. For other domain services locating properties, see http://jcifs.samba.org/src/docs/resolver.html.

LDAP Authentication

Please refer to the LDAP Integration.

HTTP Authentication Modules

Basic HTTP Authentication

Please refer to Accessing Server by HTTP for details about basic HTTP authentication.

Configuration of <TeamCity data directory> /config/auth-config.xml:

NTLM HTTP Authentication

Please refer to the NTLM HTTP Authentication.