TeamCity On-Premises 2024.03 Help

Configuring Authentication Settings

TeamCity can authenticate users via an internal database, or can integrate into your system and use external authentication sources such as Windows Domain, LDAP, or Git hosting providers.

Configuring Authentication

Authentication is configured on the Administration | Authentication page. The currently used authentication modules are also displayed there.

TeamCity provides several preconfigured authentication options (presets) to cover the most common use cases. The presets are combinations of authentication modules supported by TeamCity:

When you first sign in to TeamCity, the default authentication, including the Built-in and Basic HTTP authentication modules, is enabled.

To modify the existing settings, click Edit next to the description of the enabled authentication module.

To switch to a different preconfigured scheme, use the Load preset button.

Using Presets

To load a preconfigured set of modules, use the Load preset button, select a required option, and Apply your changes. The following presets are available:

Enabling Multiple Authentication Modules

TeamCity allows enabling multiple authentication modules simultaneously.

When a user attempts to sign in, modules will be tried 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 sign in to TeamCity.

It is possible to use a combination of internal and external authentication. The recommended approach is to configure LDAP Integration for your internal employees first and then to add Built-in authentication for external users. Since TeamCity 2020.2, you can also enable authentication via OAuth services.

To add a module:

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

  2. Use the properties available for modules by selecting checkboxes in the Add Module dialog.

  3. Click Apply and Save your changes.

General Authentication Settings

In the General Settings block, you can:

User Authentication Settings

The very first time TeamCity server starts with no users (and no administrator), so the first user is prompted for the administrator account. If you are not prompted for the administrator account, refer to How To Retrieve Administrator Password for a resolution.

The TeamCity administrator can modify the authentication settings of every user on their profile page.

The TeamCity list of users and authentication modules just map external credentials to the users. This means that a single TeamCity user can authenticate using different modules, provided the entered credentials are mapped to the same TeamCity user. Authentication modules have a configuration on how to map external user data to a TeamCity user, and some allow editing the external user linking data on the TeamCity user profile.

Handling of the user mapping by the bundled authentication modules:

  • Built-in authentication stores a TeamCity-maintained password for each user.

  • Windows Domain authentication allows specifying the default domain and assumes the domain account name is equal to the TeamCity user. The domain account can be edited on the user profile page.

  • LDAP Integration allows setting LDAP property to get TeamCity username from user's LDAP entry.

  • The modules corresponding to Git hosting providers allow admins to map users with to their external accounts by usernames. Each user can connect their own profile to an external Git hosting account in Your Profile | General | Authentication Settings.

Be cautious when modifying authentication settings: there can be a case when the administrator cannot sign in 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", they will not be able to sign in anymore: not via the default authentication since it is disabled, nor via Windows domain authentication since their Windows domain username is not equal to the TeamCity username. The solution, nevertheless, is quite simple: the administrator can sign in using the superuser account and change their TeamCity username or specify their Windows domain username on their own profile page.

Special User Accounts

By default, TeamCity has a Super User account with maximum permissions and a Guest User with minimal permissions. These accounts have no personal settings such as the Changes page and Profile information as they are not related to any particular person but rather intended for special use cases.

Credentials Authentication Modules

Built-in Authentication

By default, TeamCity uses the built-in authentication and maintains users and their passwords by itself.

When signing in to TeamCity for the first time, the user will be prompted to create the TeamCity username and password, that will be stored in TeamCity and used for authentication. If you installed TeamCity and signed in to it, it means that built-in authentication is enabled, and all user data is stored in TeamCity.

In the beginning, the user database is empty. New users are either added by the TeamCity administrator, or users register themselves if the corresponding option is enabled in the authentication module settings. All newly created users belong to the All Users 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.

By default, the users are allowed to change their password on their profile page.

Token-Based Authentication

This module allows users to authenticate via access tokens that they can create and invalidate themselves.

This authentication module is enabled by default.

Windows Domain Authentication

Allows user sign in using a Windows domain name and password. TeamCity checks these credentials: the server should be aware of the domain(s) users use to sign in. The supported syntax for the username is DOMAIN\user.name or <username>@<domain>.

In addition to signing in using the login form, you can enable NTLM HTTP Authentication single sign-on.
If you select the "Microsoft Windows Domain" preset, in addition to the login via a Windows domain, the Basic HTTP and NTLM authentication modules are enabled by default.

Specifying Default Domain

To allow users to enter the system using the login form without specifying the domain as a part of the username, do the following:

  1. Go to Administration | Authentication.

  2. Click Edit next to the Microsoft Windows domain authentication description.

  3. Set the name in the Default domain field.

  4. Click Done and Save your changes.

Registering New Users on Login

The default settings allow users to register from the login page. TeamCity usernames for the new users will be the same as their Windows domain accounts.
All newly created users belong to the All Users 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.

To disable new user registration on login:

  1. Go to Administration | Authentication.

  2. Click Edit next to the Microsoft Windows domain authentication description. Clear the Allow user registration from the login page box.

  3. Click Edit next to the NTLM HTTP authentication description. Clean the Allow user registration from the login page box.

Linux-Specific Configuration

If your TeamCity server runs under Linux, JCIFS library is used for the Windows domain login. This only supports Windows domain servers with SMB (SMBv1) enabled. SMB2 is not supported.
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 the server restart.

JCIFS library settings which cannot be changed in runtime or settings to affect HTTP NTLM settings can only be set via a properties' file passed via -Djcifs.properties JVM option.

If the default settings do not work for your environment, refer to JCIFS 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 JCIFS.

LDAP Authentication

Please refer to the dedicated page.

HTTP / SSO Authentication Modules

Basic HTTP Authentication

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

NTLM HTTP Authentication

Please refer to the dedicated page.

Bitbucket Cloud

Users can sign in to TeamCity with a Bitbucket Cloud account.

Before enabling this module, you need to configure a Bitbucket Cloud connection in the Root project's settings and a dedicated application in Bitbucket.

To sign in, click the Bitbucket icon above the login form and, after the redirect, approve the TeamCity application. If a user with your Bitbucket email is registered and this email is verified both in TeamCity and in Bitbucket, this Bitbucket account will be mapped to the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless the Allow creating new users on the first login option is disabled. It is also possible to map existing TeamCity users with Bitbucket Cloud profiles.

Setting

Description

Allow creating new users on the first login

Enabled by default. If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Allow any Bitbucket user to log in

Disabled by default.

If this option is enabled, users from any workspace can access the TeamCity server. To limit access to specific workspaces, use the Restrict authentication setting instead.

Restrict authentication

A comma-separated list of workspaces' IDs.

This list limits the set of users who can register or authenticate in TeamCity with their Bitbucket Cloud account to the specified workspaces. When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an email in one of the specified workspaces and do not have a user profile in TeamCity.

GitHub

Users can sign in to TeamCity with their GitHub.com and GitHub Enterprise accounts. TeamCity provides three independent modules for this task.

  • The GitHub.com module requires that you create an OAuth GitHub.com connection for the Root project.

  • The GitHub Enterprise module requires that you create an OAuth GitHub Enterprise connection for the Root project.

  • The GitHub App module requires that you create a GitHub App for the Root project. This connection type is available for both GitHub.com and GitHub Enterprise users.

To sign in, users must click the GitHub icon above the Username field. If a user with this GitHub email is already registered and the email is verified both in TeamCity and in GitHub, the user's GitHub account will be mapped to the respective TeamCity user, and this user will be signed in.

Otherwise, TeamCity creates a new user profile. You can disable this behavior via the corresponding authentication module setting. In this case, only users who are already registered will be able to sign in. It is also possible to map existing TeamCity users with GitHub.com profiles.

All three modules have identical settings:

Setting

Description

Allow creating new users on the first login

Enabled by default.

If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Allow any GitHub user to log in

Disabled by default.

If this option is enabled, users from any organization can access the TeamCity server. To limit access to specific organizations, use the Restrict authentication setting instead.

Restrict authentication to users from the specified organizations

A comma-separated list of organizations' IDs.

This list limits the set of users who can register or authenticate in TeamCity with their GitHub account to the specified organizations. When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an email in one of the specified organizations and do not have a user profile in TeamCity.

GitLab.com

Since version 2020.2, users can sign in to TeamCity with a GitLab.com account.

Before enabling this module, you need to configure a GitLab.com connection in the Root project's settings and a dedicated application in GitLab.

To sign in, click the GitLab icon above the login form and, after the redirect, approve the TeamCity application. If a user with your GitLab email is registered and this email is verified both in TeamCity and in GitLab, this GitLab account will be mapped with the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless the Allow creating new users on the first login option is disabled. It is also possible to map existing TeamCity users with GitLab.com profiles.

Setting

Description

Allow creating new users on the first login

Enabled by default.

If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Allow any GitLab user to log in

Disabled by default.

If this option is enabled, users from any group can access the TeamCity server. To limit access to specific groups, use the Restrict authentication setting instead.

Restrict authentication

A comma-separated list of groups' IDs.

This list limits the set of users who can register or authenticate in TeamCity with their GitLab account to the specified groups. When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an email in one of the specified groups and do not have a user profile in TeamCity.

GitLab CE/EE

Users can sign in to TeamCity with a GitLab CE/EE account.

Before enabling this module, you need to configure a GitLab CE/EE connection in the Root project's settings and a dedicated application in GitLab.

To sign in, click the GitLab icon above the login form and, after the redirect, approve the TeamCity application. If a user with your GitLab email is registered and this email is verified both in TeamCity and in GitLab, this GitLab account will be mapped with the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless the Allow creating new users on the first login option is disabled. It is also possible to map existing TeamCity users with GitLab CE/EE profiles.

Setting

Description

Allow creating new users on the first login

Enabled by default.

If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Allow any GitLab user to log in

Disabled by default.

If this option is enabled, users from any group can access the TeamCity server. To limit access to specific groups, use the Restrict authentication setting instead.

Restrict authentication

A comma-separated list of groups' IDs.

This list limits the set of users who can register or authenticate in TeamCity with their GitLab account to the specified groups. When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an email in one of the specified groups and do not have a user profile in TeamCity.

Google

Since version 2022.10, users can sign in to TeamCity with a Google account.

Before enabling this module, you need to configure a Google connection in the Root project's settings.

To sign in, click the Google icon above the login form and, after the redirect, approve the TeamCity application. If a user with your Google email is registered and this email is verified in TeamCity, this Google account will be mapped to the respective TeamCity user, and you will be signed in. Otherwise, TeamCity will create a new user profile, unless the Allow creating new users on the first login option is disabled. It is also possible to map existing TeamCity users to Google profiles.

Setting

Description

Allow creating new users on the first login

Enabled by default.

If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Skip two-factor authentication

To reduce redundant verification, check this option if your organization already requires 2FA for users to log into their Google accounts.

If you want users to pass additional verification anyway, uncheck this setting.

Learn more: Reduce Excessive Authorization Requests.

Allow users from all domains to log in, including gmail.com

Disabled by default.

If this option is enabled, users from any domain can access the TeamCity server. To limit access to specific domains, use the Restrict authentication setting instead.

Restrict authentication

A comma-separated list of organizations' domains. For example, company.com,another.com.

This list limits the set of users who can register or authenticate in TeamCity with their Google account to the users of the specified domains.

When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an email in one of the specified domains and do not have a user profile in TeamCity.

JetBrains Space

Before enabling this module, you need to create a dedicated application in JetBrains Space and configure a connection to it in the Root project's settings, as described here.

After the connection is configured, go to Administration | Authentication and:

  1. Click Add module and choose the JetBrains Space type.

  2. Choose whether you want to allow creating new users on the first login. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

  3. Uncheck the Skip two-factor authentication setting if you want users to pass an additional 2FA verification when they log in (even if they pass it when log into Space). Learn more: Reduce Excessive Authorization Requests.

  4. Save the module.

To sign in, click the JetBrains Space icon above the TeamCity login form and, after the redirect, approve the TeamCity application.

Azure DevOps Services

Before enabling this module, you need to create a dedicated connection to your Azure DevOps Services instance in the Root project's settings.

Setting

Description

Skip two-factor authentication

To reduce redundant verification, check this option if your organization already requires 2FA for users to log into their Azure DevOps accounts.

If you want users to pass additional verification anyway, uncheck this setting.

Learn more: Reduce Excessive Authorization Requests.

Allow creating new users on the first login

Enabled by default.

If this option is disabled, TeamCity will not create a new user when the provided external email is unrecognized. This is helpful if you use a publicly available TeamCity server and want to limit access to it.

Allow any Azure user to log in

Disabled by default.

If this option is enabled, users from any organization can access the TeamCity server. To limit access to specific organizations, use the Restrict authentication setting instead.

Restrict authentication

A comma-separated list of Azure DevOps organizations.

This list limits the set of users who can register or authenticate in TeamCity with their Azure account to the users of the specified organizations.

When combined with the Allow creating new users on the first login option, this setting allows automatically registering users who have an account in one of the specified organizations and do not have a user profile in TeamCity.

To sign in, click the Azure DevOps icon above the TeamCity login form and, after the redirect, approve the TeamCity application.

HTTP SAML 2.0

This module enables single sign-on authentication in TeamCity via SAML 2.0. It is confirmed to support Okta, OneLogin, AWS SSO, AD FS, and other SSO providers.

The module relies on the verified third-party SAML Authentication plugin.

To enable the module, in Administration | Authentication:

  1. Click Add module and choose the HTTP-SAML.v2 type.

  2. Save the settings and go to Administration | SAML Settings.

  3. Copy the Single Sign-On URL (Recipient) value under the Service Provider Configuration section. It should be entered in the settings of your SSO application, as described below.

Before configuring SAML settings in TeamCity, you need to create a dedicated application on your SSO provider's side. Here is an example quick instruction for Okta:

  1. In the Okta dashboard, open Applications.

  2. Click Create app integration and choose the SAML 2.0 type.

  3. Name the app and, on the Configure SAML tab, enter the single sign-on URL of your TeamCity server which you copied in Step 3 of the above instruction.

  4. Save the app.

  5. On the Assignments tab of the app's settings, click Assign and select all the people from your Okta group who will be granted access to the TeamCity server.

  6. On the General tab, click View Setup Instructions. You will see the configuration values that need to be copied to TeamCity.

You can find the detailed how-to for Okta in the plugin's repository. Settings for other SSO providers may vary, but the key actions are the same:

  • Enter the TeamCity single sign-on URL in the app's settings.

  • Ensure that all the required SSO user profiles are associated with the app.

  • Copy the values of the app's SSO URL, issuer URL, and certificate.

After the app is created, proceed with configuring SAML Settings in TeamCity:

Setting

Description

Identity provider configuration

Enter the values of the SSO URL, issuer URL, and certificate copied from the app's settings.

Optionally, you can upload an extra certificate whenever you are about to update one on the SSO provider's side. Having a new certificate preloaded in TeamCity will ensure uninterrupted trusted connection with the provider during and after the update.

Service provider configuration

Contains the autogenerated SSO URL of a recipient server, that is TeamCity. This URL has to be entered when configuring this integration on the SSO provider's side.

After you save the SAML settings for the first time, TeamCity exports them to the SP metadata XML file. The download link to this file is provided in this settings section. You can upload this file on your SSO provider's side to apply the TeamCity configuration automatically.

Create users automatically

If TeamCity detects that the email of a user who is signing in via SAML already belongs to some TeamCity user profile, it will authenticate them as this user.

If it does not recognize the email, the behavior depends on the value of this option:

  • If enabled, it will create a new user profile with this email.

  • If disabled, it will refuse to authorize this user.

Login Button Label

Defines the name of the SSO login button on the login form.

SAML Strict Mode

Checks that the request URL conforms to the expected callback URL (configured as the Teamcity root URL). We highly recommended leaving this option enabled for production environment, as an extra security check.

SAML Callback CORS Filer Exception

Adds an exception to the Teamcity CORS filter: if a POST request is sent to the SAML login callback URL and it contains a SAML message, it is considered CORS-safe.

Hide login form

Allows hiding a regular login form with a TeamCity internal username and password so users are not distracted on it.

Last modified: 27 March 2024