NTLM HTTP Authentication

The TeamCity NTLM HTTP authentication feature employs Integrated Windows Authentication and allows transparent/SSO login to the TeamCity web UI when using browsers/clients supporting NTLM, Kerberos or Negotiate HTTP authentications. Generally, it allows users to log in into the TeamCity server using their NT domain account without the need to enter credentials manually.

Configuration

The NTLM HTTP module is configured on the Administration | Authentication page under the "HTTP authentication modules" section.

Configure <TeamCity data directory> /config/auth-config.xml as follows:

<auth-config>
    <auth-modules>
        <auth-module type="HTTP-NTLM">
            <!-- "allowProtocols" property specifies the enabled protocols. Default is "ntlm". Possible protocols are "ntlm", "negotiate", "kerberos".
                 Protocol names are case insensitive and can be separated by comma, semicolon or spaces. Order is not important. -->
            <property key="allowProtocols">ntlm,negotiate</property>

            <!-- "forceProtocols" property specifies the protocols, which TeamCity uses to force NTLM HTTP authentication (i.e. to initiate NTLM HTTP authentication process
                 instead of redirecting to login page when user is not authenticated). Default is "" (empty). Possible protocols are "ntlm", "negotiate", "kerberos".
                 Protocol names are case insensitive and can be separated by comma, semicolon or spaces. Order is not important. -->
            <property key="forceProtocols"></property>

            <!-- "allowCreatingNewUsersByLogin" property specifies what TeamCity must do when user succeeded to login
                 via NTLM HTTP authentication, but does not yet exist in TeamCity (so on first successful login via NTLM HTTP authentication).
                 "true" (default) means to allow login and create such TeamCity user, while "false" means to deny login for such user. -->
            <property key="allowCreatingNewUsersByLogin">true</property>
        </auth-module>
        <!-- Another authentication modules can be configured here as well -->
    </auth-modules>
    <!-- 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 allowed (true|false) -->
    <guest-login allowed="true" />
</auth-config>

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 roles are needed for the newly registered users, these roles should be granted via the All Users group.

Since TeamCity 8.0, NTLM HTTP authentication does not require adding Windows domain authentication anymore. You can enable NTLM login with any login module once the TeamCity username is the same as the Windows domain username or the Windows domain username is specified on the user profile.

The protocols supported include NTLMv1, NTLMv2, Kerberos and Negotiate.

Requirements

The authenticating user should be logged in to the workstation with the domain account that is to be used for the authentication.
The user's web browser should support NTLM HTTP authentication.

Enabling NTLM HTTP Authentication

After the NTLM HTTP authentication module is configured, users will see a link on the login screen which, when clicked, will force the browser to send the domain authentication data.

You can force the server to announce NTLM HTTP authentication by specifying protocols in the "Force protocols" setting. This will make the server request domain authentication for any request to the TeamCity web UI. If the user's browser is run in the domain environment, the current user will be logged in automatically. If not, the browser will pop up a dialog asking for domain credentials.

Without this attribute, NTLM HTTP authentication will work only if the client explicitly initiates it (e.g. clicks the "Login using NT domain account" link on the login page), and in usual case an unauthenticated user will be simply redirected to the TeamCity login page. Since version 7.1.1, TeamCity server forces NTLM HTTP authentication only for Windows users by default. If you want to enable it for all users, set the following internal property:

teamcity.ntlm.ignore.user.agent=true

There are two more ways to force NTLM authentication for a certain connection (there is no necessity to set the forceProtocols attribute for this case):

Send request to <Your TeamCity server URL>/ntlmLogin.html and TeamCity will initiate NTLM authentication and redirect you to the overview page.
Send request to <Your TeamCity server URL>/ntlmAuth/<path> and TeamCity will initiate NTLM authentication and show you the <path> page (without redirect).

Using NTLM HTTP Authentication Module with LDAP Authentication

When using LDAP authentication, it is possible to deny login for some users. The NTLM HTTP authentication module (as well as the Windows domain credentials authentication module) does not have such functionality, so it can be possible for some users to log in using Windows domain account even if they are not allowed to log in via LDAP. To solve this problem, you should enable the Allow creating new users on the first login option for the corresponding authentication module.

With this property set, a user will be able to log in via their NT domain account only if he/she already has an existing account in TeamCity (i.e. if he/she has already logged into TeamCity earlier via LDAP) with a TeamCity username which equals the Windows domain username or a custom NT domain username specified on the user's profile page.

Configuring client

Depending on your environment, you may need to configure your client to make NTLM authentication work.

Internet Explorer

Open "Tools" -> "Internet Options".
On the "Advanced" tab make sure the option "Security -> Enable Integrated Windows Authentication" is checked.
On the "Security" tab select "Local Intranet" -> "Sites" -> "Advanced" and add your TeamCity server URL to the list.

Google Chrome

On Windows, Chrome normally uses IE's behaviour, see more information here.

Mozilla Firefox

Type about:config in the browser's address bar.
Add your TeamCity server URL to the network.automatic-ntlm-auth.trusted-uris property.

Troubleshooting

Helpful links:

Last modified: 20 April 2023