Two-factor authentication

Two-factor authentication options available in ThingsBoard
How to enable two-factor authentication for the platform
Two-factor authentication for the user login
Next steps

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.

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 tenant administrator 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:

Log in to ThingsBoard as the tenant administrator;
Navigate to the “Two-factor authentication” page of the “Security” section;
Uncheck the box labeled “Use system two factor auth settings”. Choose one or more 2FA verification methods (such as SMS, email, or authenticator app), and set up details like verification message template, verification code lifetime, total allowed time for verification, etc.;
Save changes to apply the configuration.

Log in to ThingsBoard as the system administrator or tenant administrator. Navigate to the "Two-factor authentication" page of the "Security" section. Uncheck the box labeled "Use system two factor auth settings";

Choose one or more 2FA verification methods (such as SMS, email, or authenticator app), and set up details like verification message template, verification code lifetime, total allowed time for verification, etc. Save changes to apply the configuration.

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.

Log in to ThingsBoard with basic credentials. In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with "Account";
Navigate to the "Security" tab. Activate the convenient verification method. One can activate multiple providers. Then, save changes.

Log in to ThingsBoard with basic credentials. In the upper right corner, click on the three dots icon. In the dropdown menu, proceed with "Account";

Navigate to the "Security" tab. Activate the convenient verification method. One can activate multiple providers. Then, save changes.

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;

Install and open the authenticator app on your mobile device;

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";

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.

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";

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;

Enter an email to receive a secret code;

Enter the 6-digit code from your verification email;

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;

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;

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;

Next steps

Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
Connect your device - Learn how to connect devices based on your connectivity technology or solution.
Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.