Configuring Authentication Settings

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. 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:

• Enable the guest login on the server and change the guest username. Please read our security notes before enabling this option.

• Customize the view of the login form: enter an introductory text and hide the default username/password fields (convenient if you prefer authentication through third-party services).

• Enable the per-project authorization mode.

• Enforce the email verification for all TeamCity users.

• Log out all currently signed in users and delete all personal access tokens.

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.

Basic HTTP Authentication

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

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.

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:

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.

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.

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.

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.

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: