Enable Two-factor Authentication
Two-factor authentication (2FA for short) adds an extra layer of security to your account. This type of multi-factor authentication requires that you enter your login and password, then enter another piece of information that should only be accessible to you.
With 2FA in YouTrack, this second piece of information is a code that is generated by a third-party authentication app. YouTrack 2FA is compatible with any app that accepts a QR code or key to pair with your Hub account. This method of authentication is based on the Time-based One-Time Password algorithm (TOTP). This algorithm is supported by a range of popular authentication apps, including Google Authenticator, 1Password, Authy, and LastPass. You can find a list of client applications that support this algorithm on Wikipedia.
YouTrack 2FA is subject to the following limitations:
Hub only requests the second factor for password-based logins. If you use an authentication method that is supported by a third-party auth module, like Google or GitHub, the second factor is not required. Many of these services support 2FA as well, so you can still protect your Hub account when you log in with these auth modules. You just need to set up 2FA for your account in the service that is supported by the auth module.
Basic authentication for the YouTrack REST API with login and password doesn't work with 2FA enabled. You can still use a permanent token to authenticate without having to disable 2FA. For more information, see Manage Permanent Tokens.
For many external applications, you can generate and use an application password. For details, see Generate Application Passwords.The service that supports Hub to Hub migration uses an application token for authentication. If you need to migrate Hub data to an external installation, you need to disable 2FA for the account that you use to log in to the migration service. Once the migration is complete, you can re-enable 2FA for your account.
Before you enable 2FA in YouTrack, you should already have an app that supports 2FA installed on your computer or mobile device.
To enable two-factor authentication for your Hub account:
- Open your Hub account:
Click your avatar, then select the Profile link.
Click the Update personal information and manage logins link.
- Locate the Two-factor authentication setting and click the Enable button.
The Enable Two-factor Authentication dialog opens.
Copy the recovery codes for your account to a separate file or store them in your password manager. These codes help you restore access to your account if you lose your phone, so be sure to store them securely.
- Use one of the following methods to pair the authentication app with your Hub account:
Scan the QR code with the built-in camera in yor mobile device. On most devices, you’re prompted to copy the code to your authentication app.
Open your authentication app and enter the key that is displayed in the dialog.
Enter the 6-digit code that is generated by your authentication app into the input field on the dialog.
- Click the Enable button.
Two-factor authentication is enabled for your Hub account.
Whenever you log in with your Hub credentials, you are asked to enter the code that is generated by your authentication app.
Account Recovery
YouTrack provides recovery codes that can be used as one-time passwords to access the application. If you no longer have access to the authentication app that is paired with the Hub account (for example, you lose your mobile phone or reset the device), you can use one of your recovery codes to log in.
Each recovery code is valid only once.
The recovery codes for your account are displayed in the dialog when you enable 2FA:
If you run out of valid recovery codes or lose access to them, contact an administrator. A user with the Update User permission can access your profile and disable two-factor authentication for you. You can then log in with just your login and password. You can re-enable the feature and pair the Hub account with a new device or restore the connection to your old one.
To learn how to disable 2FA for another user, see Disable Two-factor Authentication.
To learn how to disable 2FA for the default administrator, see Change or Restore Password and Permissions for Root.
Regenerating Secret Codes for 2FA
You can regenerate the secret for two-factor authentication at any time. This also generates new recovery codes for your account. Use this feature when:
You want to set up 2FA on a new device.
You lost the connection to your 2FA app.
You've used the last of your one-time recovery codes and need a new set.
You think that an unauthorized party has accessed the device that you use as a second factor.
A new secret is generated every time you click the Regenerate secret button.
Note that you can't use different secrets for different authentication apps. If you regenerate the 2FA secret for your account, you need to confirm the new secret in all of the devices that you use to generate authentication codes. To confirm the regenerated secret in your authentication apps, follow the same procedure that you used to enable the feature.