Managing Two-Factor Authentication
Enabling two-factor user authentication (2FA) on your TeamCity server grants it an extra level of security. Users will have to verify their identity in two steps: by providing their regular credentials plus by submitting disposable keys, generated on their personal mobile devices.
To select the required 2FA authentication mode, navigate to the Administration | Authentication page and scroll down to the General settings section. Note that only system administrators can modify authentication settings.
2FA Mode | Behavior |
|---|---|
Optional | Lets users decide whether they want to enable 2FA for their accounts. This is the default setting. System administrators can poll the |
Mandatory | Requires all users to set up 2FA within one week. The grace period starts from the moment you enable the "Mandatory" mode (for existing users), or the moment a user registers (for new users). |
Disabled | Users cannot set up 2FA. |
Critical Settings Protection
If the two-factor authentication is enabled, users who pass the 2FA checkup have one hour to modify critical user settings. Once this period expires, users must pass a new 2FA verification before they can proceed with these edits.
Actions that are blocked until a user passes another verification include:
Disabling 2FA in user profile settings
Changing user password and email
Generating access tokens
This behavior adds an extra layer of protection that prevents attackers who gain access to a user's account from modifying user settings and inflicting more damage.
You can modify the duration of this interval via the teamcity.2fa.sensitive.settings.access.duration internal property:
Force 2FA for Individual User Groups
If the global two-factor authentication mode is "Optional", you can force individual user groups to use 2FA. To do so, add the teamcity.2fa.mandatoryUserGroupKey internal property and set its value to the required group key.
User groups with mandatory 2FA mode share this requirement with their child user groups. You can use this behavior to force 2FA for multiple groups at once. To do this, create a new user group, assign its key to the teamcity.2fa.mandatoryUserGroupKey internal property, and set this group as a parent for all existing groups whose users are required to use 2FA.
If a group switched to mandatory 2FA already has users, set the teamcity.2fa.mandatory.user.group.grace.period intenral property to a required date when the grace period for these users should end. Otherwise, users without configured 2FA will be locked out of TeamCity. This property accepts values in the UNIX time format with milliseconds (for example, 1672753992000).
Reduce Excessive Authorization Requests
If your TeamCity users can log in using accounts of external services and your organization's policy requires 2FA to log into these services, you can skip additional verification when logging into TeamCity.
For example, if a user is already logged into their 2FA-protected GitHub account, they should be able to log into TeamCity using their GitHub credentials without any additional verification.
TeamCity automatically avoids sending redundant authorization requests for the following providers:
For providers that do not report whether 2FA is currently enabled, you can manually specify whether TeamCity should send 2FA requests. To do so, specify the Skip two-factor authentication option in auth module settings.
This setting is available for the following modules: