Security Settings

ThingsBoard allows System Administrators to configure security settings that control login behavior, password requirements, and JWT token parameters.

To access security settings, navigate to Security → General in the left-hand menu.

---

The general policy section controls account lockout behavior and link expiration times.

• Maximum number of failed login attempts — sets the number of unsuccessful login attempts allowed before the account is locked.
• Notification on account lockout — specify an email address to receive a notification when a user account is locked.
• User activation link TTL — defines the time-to-live (in hours) for activation links sent to new users. After this period, the link expires and a new one must be generated.
• Password reset link TTL — sets the expiration time (in hours) for password reset links sent via email.
• Mobile secret key length — determines the length of the secret key used for mobile authentication.

---

The password policy enforces rules that all user passwords must meet. Configure the following parameters:

• Minimum password length — the minimum number of characters in the password. Must be in the range of 6 to 50.
• Maximum password length — the maximum number of characters in the password. Must be greater than the minimum length.
• Minimum number of uppercase letters — minimum number of uppercase letters required in the password.
• Minimum number of lowercase letters — minimum number of lowercase letters required in the password.
• Minimum number of digits — minimum number of digit characters required in the password.
• Minimum number of special characters — minimum number of special characters (e.g. !, @, #) required in the password.
• Password expiration period in days — forces password expiration after the specified number of days. When the password expires, ThingsBoard requires the user to change it, ensuring passwords are regularly updated.
• Password reuse frequency in days — prevents users from reusing a previous password within the specified number of days.
• Allow whitespace — if checked, spaces are allowed in the password.
• Force to reset password if not valid — if checked, users whose password does not meet the current policy are required to reset it via email before logging in.

After configuring the general and password policy settings, click Save to apply the changes.

---

JSON Web Tokens (JWT) are used by ThingsBoard for authentication and session management. This section allows you to control token generation, signing, and expiration.

• Issuer name — the name of the issuer included in all generated JWT tokens. Used to identify the token source during validation.
• Signing key — a Base64-encoded string representing at least 512 bits of data. This key is used to sign JWT tokens and verify their integrity. Click Generate key to create a new random key.
• Token expiration time (sec) — the lifetime of JWT tokens in seconds. After this period, the token expires and the user must re-authenticate. Default: 9000 seconds. Minimum: 60 seconds.
• Refresh token expiration time (sec) — the lifetime of refresh tokens in seconds. Refresh tokens allow users to obtain new JWT tokens without re-entering their credentials. Default: 604800 seconds (7 days). Minimum: 900 seconds.

After configuring JWT settings, click Save to apply the changes.

---

• Configure the password policy so that users must use strong passwords containing uppercase and lowercase letters, digits, and special characters.
• Enable Two-factor authentication to add an extra layer of protection.
• Set a short User activation link TTL (e.g., 1–4 hours) to reduce the window of exposure for unactivated accounts.
• Rotate the JWT Signing key periodically or after a suspected key compromise. Note that rotating the key invalidates all active sessions.