Stand with Ukraine flag
Pricing Try it now
Professional Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker PE MQTT Broker
Documentation > Security > Two-factor authentication
Getting Started
Guides Installation Architecture API FAQ
On this page

Two-factor authentication

Two-factor authentication (2FA) adds an extra layer of security to user sign-in. When 2FA is enabled, users must complete an additional identity verification step in addition to entering their password.

This approach significantly reduces the risk of unauthorized access, even if user credentials are compromised.

ThingsBoard supports multiple 2FA verification methods, which can be enabled and configured by administrators and selectively activated by tenants.

image

Two-factor authentication methods

  • Email. A one-time verification code is sent to the user’s email address after entering valid credentials. To use email-based 2FA, a system administrator should configure an outgoing mail server.
  • SMS. A one-time verification code is sent to the user's phone number via SMS. To use SMS-based 2FA, an SMS provider must be configured by the system administrator.
  • Authenticator app (TOTP). A time-based one-time password (TOTP) is generated using an external authenticator application. Users can use popular apps such as Google Authenticator, Authy, or Duo.
  • Backup code. Backup codes are single-use codes generated by the user and stored securely (downloaded or printed). Backup codes can be used only in combination with at least one other enabled 2FA method and cannot be configured as a standalone authentication option.

Configure two-factor authentication

System administrator configures the available 2FA providers for tenants and can enforce 2FA for specific user groups.

Tenant administrators can either use the system administrator's 2FA configuration or define a custom 2FA configuration for themselves and their users.

To configure 2FA:

  • Log in to ThingsBoard as a System administrator or Tenant administrator.
  • Navigate to “Security” ⇾ “Two-factor authentication”.
  • (Tenant administrator only) Clear “Use system two factor auth settings” to configure tenant-specific settings.
  • Enable one or more verification methods:
    • Authenticator app
    • SMS
    • Email
    • Backup codes
  • Configure provider-specific options such as:
    • Verification limitations
    • Verification code check rate limit
  • Click “Save” to apply the configuration.

Note: The 2FA methods available to end users depend on the configuration defined on this page.

Log in to ThingsBoard as the System administrator or Tenant administrator.<br>- Navigate to <b>Security</b> ⇾ <b>Two-factor authentication</b> (1).<br>- If you are logged in as a Tenant administrator, uncheck the box labeled "Use system two factor auth settings" (2).
Log in to ThingsBoard as the System administrator or Tenant administrator.
- Navigate to Security ⇾ Two-factor authentication (1).
- If you are logged in as a Tenant administrator, uncheck the box labeled "Use system two factor auth settings" (2).
- Choose one or more 2FA verification methods (3), and set up details like verification message template, verification code lifetime, total allowed time for verification, etc.<br>- Save changes (4) to apply the configuration.
- Choose one or more 2FA verification methods (3), and set up details like verification message template, verification code lifetime, total allowed time for verification, etc.
- Save changes (4) to apply the configuration.

Enforced two-factor authentication

* Available to system administrators only

Starting from ThingsBoard 4.3, a System administrator can enforce 2FA for one of the following user groups: all users, system administrators, or selected (or all) tenant administrators.
When 2FA is enforced, affected users must configure and use at least one available 2FA method before they can continue using the platform.

Configuring enforced 2FA

  • Log in as a System administrator.
  • Navigate to “Security” ⇾ “Two-factor authentication”.
  • Enable “Enforce two-factor authentication”.
  • Select the user group for which you want to enforce 2FA:
    – All users
    – System administrators
    – Tenant administrators
    • (For Tenant administrators) Select specific Tenants or Tenant profiles, or leave the field empty to apply enforcement globally.
  • Configure the available 2FA providers.
  • Click “Save”.
Log in as a System administrator.<br>- Navigate to <b>Security</b> ⇾ <b>Two-factor authentication</b> (1).<br>- Enable <b>Enforce two-factor authentication</b> (2).
Log in as a System administrator.
- Navigate to Security ⇾ Two-factor authentication (1).
- Enable Enforce two-factor authentication (2).
- Select the user group for which 2FA should be enforced (3).
- Select the user group for which 2FA should be enforced (3).
Click <b>Save</b> (4).
Click Save (4).

Enforcing 2FA for tenant administrators

When enforcing 2FA for Tenant administrators, use the selector to switch between Tenant / Tenant profile scope to apply the policy only to specific tenants or tenant profiles.
If no tenants or tenant profiles are selected, the enforcement applies to all tenants or all tenant profiles, respectively.

- Enforce 2FA for Tenant administrators (1).<br>- Use the Tenant/Tenant profile selector (2) to define the 2FA scope.<br>- Specify specific tenants or tenant profiles (3). If the list is empty, the policy applies to all Tenants or Tenant profiles.
- Enforce 2FA for Tenant administrators (1).
- Use the Tenant/Tenant profile selector (2) to define the 2FA scope.
- Specify specific tenants or tenant profiles (3). If the list is empty, the policy applies to all Tenants or Tenant profiles.

Enable 2FA for a user account

Users can enable 2FA for their own accounts using one or more methods configured by the administrator.

To enable 2FA as a user:

  • Log in to ThingsBoard.
  • Open the user menu (three dots) in the top-right corner and select “Account”.
  • Navigate to the “Security” tab.
  • Enable one or more available 2FA methods and complete the setup steps.
Log in to ThingsBoard.<br>Open the user menu (three dots) (1) in the top-right corner and select "Account" (2).
Log in to ThingsBoard.
Open the user menu (three dots) (1) in the top-right corner and select "Account" (2).
Navigate to the "Security" tab (3). Enable one or more available 2FA methods and complete the setup steps (4).
Navigate to the "Security" tab (3). Enable one or more available 2FA methods and complete the setup steps (4).
Doc info icon

Important! The list of 2FA options available depends on the settings on the “Two-factor authentication” page.

Authenticator app

Enable authenticator app verification:

  • Open “Account” ⇾ “Security”.
  • Enable authentication via Authenticator app.
  • Open the authenticator app on your mobile device.
  • Scan the displayed QR code.
  • Enter the 6-digit code generated by the app.
  • Click “Done”.
Enable authentication via Authenticator app (1).
Enable authentication via Authenticator app (1).
Open the authenticator app on your mobile device (2), and click "Next" (3).
Open the authenticator app on your mobile device (2), and click "Next" (3).
Scan the displayed QR code with your verification app (4).
Scan the displayed QR code with your verification app (4).
Enter the 6-digit code generated by the app (5), and click "Next" (6).
Enter the 6-digit code generated by the app (5), and click "Next" (6).
Click "Done" (7).
Click "Done" (7).
2FA via Authentication app is enabled.
2FA via Authentication app is enabled.

Sign-in with authenticator app:

  • Enter your username and password.
  • Enter the 6-digit code generated by the authenticator app.
During sign-in, the user first enters their email and password (1).
During sign-in, the user first enters their email and password (1).
After that, the user must enter the security code generated by the authenticator app (2), and click "Continue" (3).
After that, the user must enter the security code generated by the authenticator app (2), and click "Continue" (3).

SMS verification

Enable SMS verification:

  • Open “Account” ⇾ “Security”.
  • Enable authentication via SMS.
  • Enter your phone number.
  • Enter the 6-digit code received via SMS.
  • Click “Done”.
Enable authentication via SMS (1).
Enable authentication via SMS (1).
Enter the valid phone number (2), and click "Send code" (3).
Enter the valid phone number (2), and click "Send code" (3).
Input the 6-digit code from your verification SMS (4), then click "Activate" (5).
Input the 6-digit code from your verification SMS (4), then click "Activate" (5).
The next time the user logs in, he/she will need to enter the code from SMS. Click "Done" (6);
The next time the user logs in, he/she will need to enter the code from SMS. Click "Done" (6);
2FA via SMS is enabled.
2FA via SMS is enabled.

Sign-in with SMS

During sign-in:

  • Enter your username and password.
  • Enter the verification code received via SMS.
During sign-in, the user first enters their email and password (1).
During sign-in, the user first enters their email and password (1).
After that, the user must enter the security code from the SMS message (2), and click "Continue" (3).
After that, the user must enter the security code from the SMS message (2), and click "Continue" (3).

Email verification

Enable email verification:

  • Open “Account” ⇾ “Security”.
  • Enable authentication via Email.
  • Enter the 6-digit code received via email.
  • Click “Done”, then “Save”.
Enable authentication via Email (1).
Enable authentication via Email (1).
Enter an email to receive a secret code (2), and click "Send code" (3).
Enter an email to receive a secret code (2), and click "Send code" (3).
Enter the 6-digit code from your verification email (4), then click "Activate" (5).
Enter the 6-digit code from your verification email (4), then click "Activate" (5).
Click "Done" (6).
Click "Done" (6).
2FA via email is enabled;
2FA via email is enabled;

Sign-in with email:

  • Enter your username and password.
  • Enter the verification code received via email.
During sign-in, the user first enters their email and password (1).
During sign-in, the user first enters their email and password (1).
After that, the user must enter the security code from the incoming email in their mailbox (2), and click "Continue" (3).
After that, the user must enter the security code from the incoming email in their mailbox (2), and click "Continue" (3).

Backup codes

Backup codes provide an alternative authentication method when other 2FA methods are unavailable (for example, if the mobile device is lost).

Note: this method can be used only in combination with at least one other enabled 2FA method and cannot be configured as a standalone authentication option.

Generate backup codes:

  • Open “Account” ⇾ “Security”.
  • Enable authentication via backup codes.
  • Download or print the generated backup codes and store them securely.
  • Click “Done”.

Each backup code can be used only once.

Enable authentication via backup codes (1).
Enable authentication via backup codes (1).
Download or print the generated backup codes (2) and store them securely. Click "Done" (3).
Download or print the generated backup codes (2) and store them securely. Click "Done" (3).
2FA via backup codes is enabled.
2FA via backup codes is enabled.

Sign-in with a backup code:

  • Start sign-in by entering your username and password.
  • Click “Try another way”.
  • Select “Backup code”.
  • Enter an unused backup code from your list.
  • Click “Continue”.
During sign-in, the user first enters their email and password (1).
During sign-in, the user first enters their email and password (1).
Click "Try another way" (2).
Click "Try another way" (2).
Select "Backup code" (3).
Select "Backup code" (3).
After that, the user must enter a valid 8-digit code from their backup codes list (4), and click "Continue" (5).
After that, the user must enter a valid 8-digit code from their backup codes list (4), and click "Continue" (5).

Next steps