Stop the war

Stand with Ukraine flag

Support Ukraine
Try it now Pricing
Professional Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Security > Two-Factor Authentication
Getting Started
Devices Library Guides Installation Architecture API FAQ
On this page

Two-Factor Authentication

Two-factor authentication is a state-of-the-art approach designed to provide an extra security layer. With 2FA, even though someone knows your password your ThingsBoard account is safe against malicious access.

In addition to entering a password, one must populate a secret code that comes to a pre-configured mailbox or phone. Also, a notification will be sent if someone tries to access one’s account.

The validity period of the secret and the remaining properties available for the system administrator can make online accounts invulnerable to cybercriminals.

image

Two-factor authentication options available in ThingsBoard

  • Email. With this approach, the user receives a secret code by mail after entering their valid username and password. For proper work of 2FA by email, an outgoing mail server should be configured.
  • SMS. A secret one-time code is sent to the user’s phone in short message. To receive SMS, a system administrator should set up the SMS provider properly.
  • Authenticator app. If enabled, users need to install an app on a computer or smartphone to generate a code. The software dynamically renders a short-time secrets that should be used on a second step of authentication process. A user can utilize any popular app, like Google Authenticator, Authy, or Duo.
  • Backup code. The backup code is a number of digits that the user generates in ThingsBoard and saves on secure device or prints out. Authentication with backup can be activated only in combination with any of the above types of authentication. The system administrator cannot configure a backup code approach as the only available 2FA option.

How to enable two-factor authentication for the platform

The system administrator user configures the default security policies and options for all remaining users. The former can turn on/off the possibility to use 2FA of any kind while the end user defines whether to use an additional verification or not. Follow the steps below to enable two-factor authentication for your ThingsBoard instance.

  1. Log in as a sysadmin to your ThingsBoard platform instance;
  2. Go to “Security” page — “Two-factor authentication” section;
  3. Activate and configure one or more verification methods. Edit settings for all enabled 2FA providers (verification message template, verification code lifetime, total allowed time for verification, etc) if necessary;
  4. Save changes.

image

Two-factor authentication for the user login

If enabled, users on the platform can add an extra verification of their identity to access the data. Although 2FA can be a corporate security standard, the final decision on whether to use it or not is with a particular user. Sysadmin cannot force users to authenticate with 2FA.

  1. Log in with basic credentials;
  2. In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with “Security”;
  3. Activate the convenient verification method. One can activate multiple providers;
  4. Save changes.
  • In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with "Security";
  • Activate the convenient verification method. One can activate multiple providers. Save changes.
In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with "Security";
In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with "Security";
Activate the convenient verification method. One can activate multiple providers. Save changes.
Activate the convenient verification method. One can activate multiple providers. Save changes.
Doc info icon

Important! The list of toggleable 2FA options depends on the system administrator’s settings.

2FA with Authenticator app
  • Toggle to enable authentication with the external app;
  • Install and open the authenticator app on your mobile device;
  • Scan the QR code using the application;
  • Enter the 6-digit code from authenticator;
  • The next time the user logs in, he/she will need to provide the code rendered by the application. Click "Done";
  • 2FA by Authentication app is enabled;
  • While login, on the first step the user enters the email and password. Afterward, user should enter the security code from the authenticator app.
Toggle to enable authentication with the external app;
Toggle to enable authentication with the external app;
Install and open the authenticator app on your mobile device;
Install and open the authenticator app on your mobile device;
Scan the QR code using the application;
Scan the QR code using the application;
Enter the 6-digit code from authenticator;
Enter the 6-digit code from authenticator;
The next time the user logs in, he/she will need to provide the code rendered by the application. Click "Done";
The next time the user logs in, he/she will need to provide the code rendered by the application. Click "Done";
2FA by Authentication app is enabled;
2FA by Authentication app is enabled;
While login, on the first step the user enters the email and password. Afterward, user should enter the security code from the authenticator app.
While login, on the first step the user enters the email and password. Afterward, user should enter the security code from the authenticator app.
2FA with SMS
  • Toggle to enable authentication by SMS;
  • Enter the valid phone number and expect to receive a verification short message;
  • Input the 6-digit code from your verification SMS;
  • The next time the user logs in, he/she will need to enter the code from SMS. Click "Done";
  • 2FA by SMS is enabled;
  • While login, on the first step the user enters the email and password. Afterward, user should enter the security code from your SMS.
Toggle to enable authentication by SMS;
Toggle to enable authentication by SMS;
Enter the valid phone number and expect to receive a verification short message;
Enter the valid phone number and expect to receive a verification short message;
Input the 6-digit code from your verification SMS;
Input the 6-digit code from your verification SMS;
The next time the user logs in, he/she will need to enter the code from SMS. Click "Done";
The next time the user logs in, he/she will need to enter the code from SMS. Click "Done";
2FA by SMS is enabled;
2FA by SMS is enabled;
While login, on the first step the user enters the email and password. Afterward, user should enter the security code from your SMS.
While login, on the first step the user enters the email and password. Afterward, user should enter the security code from your SMS.
2FA with email
  • Toggle to enable authentication by email;
  • Enter an email to receive a secret code;
  • Enter the 6-digit code from your verification email;
  • Click "Done";
  • 2FA by email is enabled;
  • While login, on your first step the user enters the email and password. Afterward, user should enter the security code from your mailbox.
Toggle to enable authentication by email;
Toggle to enable authentication by email;
Enter an email to receive a secret code;
Enter an email to receive a secret code;
Enter the 6-digit code from your verification email;
Enter the 6-digit code from your verification email;
Click "Done";
Click "Done";
2FA by email is enabled;
2FA by email is enabled;
While login, on your first step the user enters the email and password. Afterward, user should enter the security code from your mailbox.
While login, on your first step the user enters the email and password. Afterward, user should enter the security code from your mailbox.
2FA with a Backup code
  • Toggle to enable authentication with backup code;
  • Once turned on, the codes will be available on the screen. The user can download them (txt) or print them. Each backup code can be used once;
  • 2FA by backup code is enabled;
  • While regular login process, after email and password step click “Try another way” button;
  • Select a way to verify with a backup code;
  • Enter the 8-digit code from your backup codes list;
Toggle to enable authentication with backup code;
Toggle to enable authentication with backup code;
Once turned on, the codes will be available on the screen. The user can download them (txt) or print them. Each backup code can be used once;
Once turned on, the codes will be available on the screen. The user can download them (txt) or print them. Each backup code can be used once;
2FA by backup code is enabled;
2FA by backup code is enabled;
While regular login process, after email and password step click “Try another way” button;
While regular login process, after email and password step click “Try another way” button;
Select a way to verify with a backup code;
Select a way to verify with a backup code;
Enter the 8-digit code from your backup codes list;
Enter the 8-digit code from your backup codes list;

Next steps