Hub 2019.1 Help

App-based Authentication

One of the options for two-factor authentication in Hub lets you pair your Hub account with an external app. In this case, you need to enter a code that is generated by a third-party authentication app to log in to Hub.

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.


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

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

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

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

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

    Enable two factor authentication
    • The Enable Two-factor Authentication dialog opens.

    Enable two factor authentication dialog
  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.


If you encounter an error when attempting to set up app-based 2FA, see if the following condition applies.


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


The internal clock for you Hub server is out of sync. Many apps use a UNIX timestamp to generate authentication codes. If your server clock 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 your Hub server. Follow the instructions that are specific to your operating system and server hardware.

Last modified: 4 July 2019