Authenticating with JWT

Mode fokus
Ukuran font
Terakhir diperbarui: 2026-04-01 16:30:53
JWT authentication is a token-based authentication mechanism that does not rely on the server to retain client authentication or session information. The client submits the JWT in the password or a separate field. The MQTT server verifies the JWT signature and claims. After verification, the server accepts the client connection request.
What Is JWT
JSON Web Token (for details, see RFC 7519) is a standard for defining JSON objects transmitted over networks, and is often used in token-based authentication solutions.
The overall authentication principle is illustrated in the following figure. The application obtains a JWT from the Identity and Access Management (IAM) service. The client carries the JWT in the connection request. The MQTT Broker uses the preconfigured signature method (the example in the following figure uses a public key certificate set, but other signature methods can also be used) to verify the received JWT. If the content is consistent, it indicates that the token was not tampered with during transmission, and authentication succeeds. Otherwise, authentication fails.
﻿
JWT-based MQTT Authentication Principles
TDMQ for MQTT supports integrating external JWT services for authentication and authorization.
The client carries the JWT in the username or password field. When initiating a connection (sending the CONNECT packet), the MQTT server uses the configured key to perform signature verification and determines whether the JWT signature is valid to prevent spoofing or tampering.
After signature verification passes, the MQTT server further inspects the claim information (Claims) in the Payload, such as iss (Issuer), exp (Expiration Time), nbf (Not Before), iat (Issued At), and aud (Audience), to determine the validity of the JWT. 
exp (Expiration Time): Checks whether the token has expired. If it has expired, the connection is rejected.
nbf (Not Before): Checks whether the token has taken effect. For example, if the token takes effect after 5 minutes, attempts to connect within those 5 minutes are rejected.
iat (Issued At): Checks whether the token was issued too early.
iss (Issuer): Checks whether the token was issued by a trusted issuer.
aud (Audience): Checks whether the token was issued for the TDMQ for MQTT service, preventing a token issued for other services from being misused.
After the JWT passes signature verification and claims validation, the MQTT server accepts the client connection request.
Prerequisites
You need to implement your own JWT service to distribute JWT tokens to clients, ensuring the signature algorithm matches the configuration in the console. You can use the JWT Debugger provided by the JWT official website for debugging. Alternatively, you can use your own JWKS (JSON Web Key Set) server for authentication. Ensure the JWKS server is available and accessible from the TDMQ for MQTT server.
Additionally, to ensure security, note the following:
1. Do not carry sensitive information in the JWT payload.
2. The JWT itself contains authentication information. Once leaked, the holder gains all privileges of the token. To reduce risk, set a short validity period for JWTs.
3. Grant JWTs based on business scenarios for security considerations.
4. Ensure the transmission link is secure. Avoid transmitting data in plaintext over the public network.
Configuring JWT Authentication
1. Log in to the MQTT Console.
2. Click Resource Management > Cluster Management in the left sidebar. Select a region, click the ID of the target cluster to configure the certificate, and enter the Cluster Basic Information page.
3. Click Authentication Management, and switch to JWT Authentication. Click Enable Authentication.
﻿
4. Complete the JWT authentication and authorization configuration in the pop-up window. Two authentication methods are supported: JWT and JWKS.
JWT Authentication
JWKS Authentication
Complete the configuration based on the following instructions:
Authentication Field: Specify whether the MQTT client carries the JWT token in the Username or Password field of the CONNECT packet.
Signature Method: The signature algorithm for the JWT token. Currently, HMAC-based and public-key methods with various primary algorithms are supported. When using a public key, enter the key in .pem file format.
Key: Enter the corresponding key based on the selected signature method. The key content is defined by you according to encryption standards.
Description: Optional. Enter as needed. The description cannot exceed 128 characters.
﻿
TDMQ for MQTT also supports using JWKS (JSON Web Key Set) for JWT authentication. Complete the configuration based on the following instructions:
Authentication Field: Specify whether the MQTT client carries the JWT token in the Username or Password field of the CONNECT packet.
Source of Authentication Information: JWKS server authentication and JSON authentication are supported.
Server Authentication: The JWKS server refers to the MQTT server dynamically obtaining the public key set from a specified address. Therefore, you need to enter the JWKS server address and the interval for periodically retrieving the public key set from the server.
When the JWKS endpoint provided by your IAM is accessible via the public network, select Server Authentication.
Server Address: The JWKS endpoint address provided by the IAM service. The endpoint should comply with the OIDC specification and should not include the /.well-known/jwks.json portion. See your IAM service provider's documentation or the Auth0 guide.
Refresh Interval: The interval for the MQTT Broker to refresh the public key set from the IAM service. The default value is 60s.
JSON Authentication: The JSON authentication method means you maintain a fixed public key set. The MQTT server selects specific public keys from the set for signature verification based on request rules. The authenticator uses the exp (Expiration Time), nbf (Not Before), and iat (Issued At) parameters from the public key list queried at the JWKS endpoint.
When the IAM provider's JWKS endpoint is not accessible from the MQTT Broker network, select JSON Authentication. Download the jwks.json file from the IAM provider and copy the content to the textbox.
﻿
5. After completing the configuration, click Save.
﻿