ApsaraMQ for MQTT supports X.509 certificate-based authentication to verify identities between brokers and clients during TLS handshakes. Certificates are exchanged before a connection is established, preventing unauthorized access.
| Mode | Verification | Instance requirement |
|---|---|---|
| One-way authentication | The client verifies the broker's identity using a server certificate. | All instance types |
| Mutual authentication | Both sides verify each other. The client checks the server certificate, and the broker checks the device certificate. | Enterprise Platinum Edition only |
One-way authentication
In one-way authentication, the client validates the broker's server certificate during the TLS handshake. The broker automatically presents its server certificate when the client initiates a connection. If the certificate passes validation, the connection is established.
Switch to one-way authentication
This procedure applies only to Enterprise Platinum Edition instances. All other instance types support one-way authentication by default.
Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.
In the top navigation bar, select the region where your instance resides. On the Instances page, click the instance name to go to the Instance Details page.
In the left-side navigation pane, choose Certificates > Server Certificate.
Click One-way Authentication. Read the confirmation message and click OK. Wait for the broker to restart.
Sample code for server certificate validation
| Language | Sample code |
|---|---|
| Java | mqtt.demo.java |
| Python | mqtt.demo.python |
| C | mqtt.demo.c |
| .NET | mqtt.demo.net |
| JavaScript | mqtt.demo.javascript |
| iOS | mqtt.demo.ios |
Mutual authentication
Mutual authentication adds a second layer of verification: in addition to the client validating the broker's server certificate, the broker also validates the client's device certificate. This prevents unauthorized devices from connecting to the broker.
Mutual authentication requires an Enterprise Platinum Edition instance.
Certificate types
Mutual authentication uses three certificate types:
| Certificate | Role | Management |
|---|---|---|
| CA certificate | Root of trust. Issues server, device, and validation certificates. | Register with the broker. |
| Server certificate | Identifies the broker. | Host in Certificate Management Service and restart the instance to apply. |
| Device certificate | Identifies each client. Must be globally unique. | Auto-registered on first connection. |
How it works
When a client connects, the client interacts with the broker based on TLS 1.2. The broker validates the device certificate through the following process:
The client initiates a TCP connection and sends its device certificate to the broker over the MQTT protocol.
The broker checks whether the device certificate is registered.
Registered: The broker checks the certificate status. If activated, the broker proceeds to validate the certificate (step 5). If not activated, the connection is rejected.
Not registered: The broker attempts to match the device certificate to a CA certificate (step 3).
The broker looks up the CA certificate that corresponds to the device certificate.
CA certificate found and registered: The broker checks the CA certificate status (step 4).
CA certificate not found: The connection is rejected.
The broker checks whether the CA certificate is activated.
Activated: The broker proceeds to validate the device certificate (step 5).
Not activated: The connection is rejected.
The broker validates the device certificate against the registered CA certificate.
Validation passes: The client is authenticated (step 6).
Validation fails: The connection is rejected.
Authentication succeeds. The client connects and can start sending and receiving messages.
On the first connection, the broker automatically matches the device certificate to the corresponding CA certificate and registers it. Subsequent connections skip the CA matching step and validate the device certificate directly.
Set up mutual authentication
Configure mutual authentication in three steps:
Step 1: Register a CA certificate with the broker.
Obtain a CA certificate by applying to a Certificate Authority (CA) or by creating your own. Then register it with the ApsaraMQ for MQTT broker. A CA certificate can issue device, server, and validation certificates.
Step 2: Issue and deploy a server certificate.
Issue a server certificate from your CA certificate, host it in Certificate Management Service, and restart the ApsaraMQ for MQTT instance for the certificate to take effect.
See Manage server certificates.
Step 3: Issue a device certificate.
Issue a device certificate from your CA certificate. Each device certificate must be globally unique. Register the device certificate with the broker before use.
On the first connection, the broker automatically matches the device certificate with the corresponding CA certificate and registers it. Subsequent connections skip the CA matching step and validate the device certificate directly.
Sample code for device certificate validation
| Language | Sample code |
|---|---|
| Java | mqtt.bissl.demo.java |
| Python | mqtt.ssl.mode.demo.python |
| C | mqtt.ssl.demo.c |
| .NET | mqtt.ssl.mode.demo.net |
| JavaScript | mqtt.ssl.demo.javascript |
| iOS | mmqtt.ssl.demo.ios |
API operations
CA certificate management
Device certificate management
Console operations
Host a purchased or self-issued server certificate in Certificate Management Service, then use it to initialize the ApsaraMQ for MQTT instance. See Manage server certificates.
Register, activate, deactivate, or delete CA certificates. See Manage CA certificates.
Query, activate, deactivate, or delete device certificates. See Manage device certificates.