App-based Authentication
One of the options for two-factor authentication in YouTrack lets you pair your account with an external app. In this case, you need to enter a code generated by a third-party authentication app to log in to YouTrack.
Supported Apps
App-based 2FA is compatible with any app that accepts a QR code or key to pair with your 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.
Limitations
App-based authentication in YouTrack is subject to the following limitations:
You are limited to one type of two-factor authentication. This means that you can't use token-based authentication together with app-based authentication. Once you pair your account with a hardware token, the option to set up app-based authentication is not available. To switch from token-based authentication to app-based 2FA, you must first unregister the hardware device that you currently use as a second factor.
YouTrack only requests the second factor for password-based logins. If you use an authentication method 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 account when you log in with these auth modules. You just need to set up 2FA for your account in the service supported by the auth module.
If you are a member of a group for which 2FA is required, you must set up a second authentication factor for any auth modules that support login with a username and password. You can either delete your password-based credentials and continue to log in with third-party authentication or set up 2FA for your account as described here.
Basic authentication for the Hub REST API with username 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.
To circumvent 2FA in an external application, generate and use an application password instead. For details, see Generate Application Passwords.
Enable App-based 2FA
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 YouTrack account:
Click your avatar in the header, then select the Profile link.
Switch to the Account Security tab.
In the Two-factor authentication section of the page, click the Pair with app 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 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 displayed in the dialog.
You can use the same QR code or secret key to pair your account with apps on multiple devices.
Enter the 6-digit code generated by your authentication app into the input field on the dialog.
Click the Enable button.
Two-factor authentication is enabled for your account.
Whenever you log in with your YouTrack credentials, you are asked to enter the code generated by your authentication app.
Account Recovery
When you pair your account with an authentication app, YouTrack generates a set of one-time recovery codes. These codes let you log in to your account even when you don't have access to your authentication app.
To log in with a recovery code:
Open the YouTrack login page.
Enter your username and password, then click the Log in button.
When YouTrack asks you to enter the code generated by your authentication app, enter one of your recovery codes instead.
Your recovery codes are for one-time use only. After you sign in with a recovery code, be sure to note that the code is no longer valid.
If you don't have access to or have used all of your recovery codes, 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 username and password. You can re-enable the feature and pair the 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 Manage or Restore the Default Administrator Account.
If your installation supports third-party authentication modules, you can also try to log in using a third-party service that doesn't require a second authentication factor. Buttons for each active authentication module are shown at the bottom of the login form.
These login options are redirected through the third-party service, so YouTrack won't ask you for an authentication code.
Troubleshooting
If you encounter an error when attempting to set up app-based 2FA, see if the following condition applies.
Condition — You repeatedly enter codes that are generated by an authenticator app (for example, Google Authenticator) without success. Hub displays the error message Code <code> is not a valid two-factor authentication code for user <username>.
Cause | Solution |
The internal clock for your device is out of sync. Many apps use a UNIX timestamp to generate authentication codes. If the internal clock for your device is even as little as one minute out of sync, the codes expire before you have a chance to enter them in the confirmation dialog. | Manually sync the internal clock for the device that runs your authentication app with the current time. Follow the instructions that are specific to your operating system and device hardware. If this still doesn't solve the problem, contact an administrator. This problem can also arise when the internal clock for your Hub server is out of sync. |