App-based Authentication

Supported Apps

App-based 2FA in Hub 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.

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

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

  To circumvent 2FA in an external application, generate and use an application password instead. For details, see Generate Application Passwords.

• You can't migrate Hub data to another Hub installation with an account that uses 2FA. 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.

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 Hub account:

tip

Requires permissions: Update Self

1. Open your Hub account. To access your Hub account in a YouTrack installation that uses a built-in Hub service:

   • Click your avatar in the header, then select the Profile link.

   • Click the Update personal information and manage logins link next to the Hub account setting in your YouTrack profile.

2. Locate the Two-factor authentication setting and click the Pair with authentication app link.

   

   • The Enable Two-factor Authentication dialog opens.

   

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

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

   You can use the same QR code or secret key to pair your Hub account with apps on multiple devices.

5. Enter the 6-digit code that is generated by your authentication app into the input field on the dialog.

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

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:

1. Open the YouTrack login page.

2. Enter your username and password, then click the Log in button.

3. When YouTrack asks you to enter the code that is 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 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.

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.