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. 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.
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:
Click Add Module and select a module from the drop-down menu.
Use the properties available for modules by selecting checkboxes in the Add Module dialog.
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.
User Authentication Settings
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.
Modules, corresponding to Git hosting providers, allow admins mapping users with their external accounts by usernames. Each user can connect 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 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.
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 which 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.
HTTP / SSO Authentication Modules
Basic HTTP Authentication
Please refer to Accessing Server by HTTP for details about the basic HTTP authentication.
Bitbucket Cloud
Since version 2020.2, 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 with the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless this 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. |
Restrict authentication | A comma-separated list of workspaces' IDs. This list limits a set of users who can register or authenticate in TeamCity with their Bitbucket Cloud account. Together with the enabled Allow creating new users on the first login option, this leaves an ability to automatically register unknown users but restricts it to those who work on your projects. Leave empty to allow all Bitbucket Cloud users to access the TeamCity server. |
GitHub.com
Since version 2020.2, users can sign in to TeamCity with a GitHub.com account.
Before enabling this module, you need to configure a GitHub.com connection in the Root project's settings and a dedicated application in GitHub.
To sign in, click the GitHub icon above the login form and, after the redirect, approve the TeamCity application. If a user with your GitHub email is registered and this email is verified both in TeamCity and in GitHub, this GitHub account will be mapped with the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless this option is disabled*. It is also possible to map existing TeamCity users with GitHub.com profiles.
| Setting | Description |
|---|---|
* Allow creating new users on the first login | Enabled by default. |
Restrict authentication | A comma-separated list of organizations' IDs. This list limits a set of users who can register or authenticate in TeamCity with their GitHub account. Together with the enabled Allow creating new users on the first login option, this leaves an ability to automatically register unknown users but restricts it to those who work on your projects. Leave empty to allow all GitHub users to access the TeamCity server. |
GitHub Enterprise
Since version 2020.2, users can sign in to TeamCity with a GitHub Enterprise account.
Before enabling this module, you need to configure a GitHub Enterprise connection in the Root project's settings and a dedicated application in GitHub.
To sign in, click the GitHub icon above the login form and, after the redirect, approve the TeamCity application. If a user with your GitHub email is registered and this email is verified both in TeamCity and in GitHub, this GitHub account will be mapped with the respective TeamCity user and you will be signed in. Otherwise, TeamCity will create a new user profile, unless this option is disabled*. It is also possible to map existing TeamCity users with GitHub Enterprise profiles.
| Setting | Description |
|---|---|
* Allow creating new users on the first login | Enabled by default. |
Restrict authentication | A comma-separated list of organizations' IDs. This list limits a set of users who can register or authenticate in TeamCity with their GitHub account. Together with the enabled Allow creating new users on the first login option, this leaves an ability to automatically register unknown users but restricts it to those who work on your projects. Leave empty to allow all GitHub users to access the TeamCity server. |
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 this 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. |
Restrict authentication | A comma-separated list of groups' IDs. This list limits a set of users who can register or authenticate in TeamCity with their GitLab account. Together with the enabled Allow creating new users on the first login option, this leaves an ability to automatically register unknown users but restricts it to those who work on your projects. Leave empty to allow all GitLab users to access the TeamCity server. |
GitLab CE/EE
Since version 2020.2, 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 this 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. |
Restrict authentication | A comma-separated list of groups' IDs. This list limits a set of users who can register or authenticate in TeamCity with their GitLab account. Together with the enabled Allow creating new users on the first login option, this leaves an ability to automatically register unknown users but restricts it to those who work on your projects. Leave empty to allow all GitLab users to access the TeamCity server. |