Token-based Authentication
One of the options for two-factor authentication in YouTrack lets you pair your account with a hardware token. In this case, you need to interact with a hardware device in your possession to log in to YouTrack.
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+
Apple Safari 14+
Microsoft Internet Explorer doesn't support U2F, and is also no longer supported by YouTrack.
Supported Devices
Token-based 2FA in YouTrack is based on the FIDO2 specification. This implementation lets you work with common devices to authenticate 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.
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 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 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 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 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 account with a hardware token in a mobile browser should be similar.
To enable token-based two-factor authentication in a web browser:
Click your avatar in the header, then select the Profile link.
Switch to the Account Security tab.
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 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.
Connect and activate the hardware device. When activated properly, the device is paired with your account.
Two-factor authentication is enabled for your account.
Whenever you log in with your YouTrack 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 username and password. You can re-enable the feature and pair your 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.