TeamCity On-Premises 2023.05 Help

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.

Available 2FA modes

2FA Mode



Lets users decide whether they want to enable 2FA for their accounts. This is the default setting.


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


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:

teamcity.2fa.sensitive.settings.access.duration.seconds=45 # or teamcity.2fa.sensitive.settings.access.duration.minutes=5 # or teamcity.2fa.sensitive.settings.access.duration.hours=3

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.

Parent user group with enforced 2FA

See Also

Last modified: 19 May 2023