Token-based Authentication

Supported Web Browsers

Token-based 2FA in YouTrack requires native support for the universal second factor (U2F) protocol from the web browser. The protocol is supported in the following web browsers:

• Google Chrome 73+

• Microsoft Edge for Windows 10 version 1809+

• Mozilla Firefox 57+

• Opera 54+

The following web browsers are either unsupported or not recommended:

• Microsoft Internet Explorer doesn't support U2F, and is also no longer supported by YouTrack.

• In Apple Safari, U2F support is only available in versions 12.1 and higher as an experimental feature. Our efforts to test token-based 2FA with the experimental feature enabled were inconclusive. For best results, we recommend that you switch to a web browser that supports UTF as a baseline feature.

Supported Devices

Token-based 2FA in YouTrack is based on the FIDO2 specification. This implementation lets you work with common devices to authenticate with Hub from your mobile device or desktop computer. The feature is compatible with any device that is FIDO2 compliant, including:

• Hardware security keys from manufacturers like Yubico, HID Global, and Feitian.

• Biometric technologies that are supported by your operating system, like built-in fingerprint sensors.

There are known compatibility issues with Windows Hello in the current release. We hope to support the sign-in mechanisms that use this technology in the near future.

If you want to sign in with your fingerprint using Touch ID on a MacBook, we recommend that you use Chrome for macOS. Firefox and other browsers don't provide support this feature at this time.

note

Any biometric information that you deliver to the hardware device is not relayed to YouTrack. YouTrack does not request, store, or process your biometric data.

Limitations

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

• You can't pair your Hub account with more than one hardware device. This means that you aren't able, for example, to authenticate with a hardware security key when you log into YouTrack in a web browser on your desktop computer and separately authenticate with the built-in fingerprint sensor when you log into YouTrack in a mobile browser.

  For details, see Token-based 2FA for Desktop and Mobile.

• You should always access YouTrack from the same URL that you used to register the device. The authentication protocol uses built-in domain tracking to prevent phishing attacks.

The following limitations apply to all types of two-factor authentication in YouTrack:

• 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 Token-based 2FA

Before you enable token-based 2FA in YouTrack, you should verify that this feature is supported in your web browser and the hardware device that you want to use as a second factor supports the FIDO2 specification. For details, see Supported Web Browsers and Supported Devices.

The following instructions describe how to set up hardware-based 2FA in a web browser. The procedure for pairing your Hub account with a hardware token in a mobile browser should be similar.

To enable token-based two-factor authentication in a web browser:

tip

Requires permissions: Update Self

1. Open your Hub profile by clicking your avatar, then selecting Profile.

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

   

   • Your browser displays a dialog with additional instructions for pairing with the hardware device. The actual dialog and setup instructions vary based on your operating system, browser, and hardware device.

     This example shows the dialog that is presented in Chrome for Windows on a device that doesn't have a built-in fingerprint sensor.

     

     Here's the same dialog as shown in Chrome for macOS on a MacBook that supports Touch ID.

     

3. Connect and activate the hardware device. When activated properly, the device is paired with your Hub account.

   • Two-factor authentication is enabled for your Hub account.

   • Whenever you log in with your Hub credentials, you are prompted to connect with the paired device if it isn't detected automatically.

Token-based 2FA for Desktop and Mobile

If you want to use token-based authentication as a second factor on desktop and mobile, you need to pair with a single device that is compatible with both platforms. Many hardware security keys are designed to be plugged into a USB 3.x port, which most mobile devices don't have. If you secure your account with this type of device in the browser on your desktop machine, you will probably need to use an adapter to authenticate with this device on your mobile devices. Here are a few alternatives that you might use to authenticate on both desktop and mobile:

• Use a security key that connects to a USB-C port. While this type of connection is widely supported by both desktop and mobile devices, some devices may still require an adapter.

• Use a security key that supports near-field communication (NFC). These keys can usually be plugged into the USB port on your desktop computer and connect to a mobile device over NFC. To pair the security key with your account on a mobile device, the mobile device must support NFC as well.

• Use a security key that supports a Bluetooth connection. These keys can pair with both desktop and mobile clients that support this standard.

Keep in mind that you only need to provide a second authentication factor on your mobile device when you work with YouTrack in a mobile browser. If you're only working with YouTrack, you can download and install YouTrack Mobile and authenticate with an application password instead. For details, see Generate Application Passwords.

Account Recovery

If you lose the paired hardware device and can no longer log in to YouTrack, 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.