MQTT Broker Authentication

ClearBlade IoT Enterprise supports various types of authentication with the MQTT broker. Use the Quick Reference below to find the right method for your device, then follow the detailed instructions in the relevant section.

Quick Reference

Which method should I use?

Ports at a glance

Auth Tokens

Two-step process:

1. Connect to port 8905 (non-TLS) or 8906 (TLS) to obtain a token.

2. Use that token to connect to the broker on port 1883 (non-TLS) or 1884 (TLS). Both connections are to the same platform URL.

Obtaining a ClearBlade auth token over MQTT

A ClearBlade authentication token can either be obtained via a REST endpoint call (see REST Authentication) or MQTT. To retrieve a token via MQTT, a separate connection must first be made on a different port, before continuing with your normal MQTT connection. See the table below for details.

Connect

Note: The Password field (System Secret) was deprecated as of ClearBlade Platform version 9.38.0. Consult your platform documentation for the current credential to use.

Subscribe

• To receive the new JWT token, subscribe to the "auth" topic (recommended).

• To receive the legacy token, subscribe to the "v/1/auth" topic.

Extract token

ClearBlade publishes the user token on the auth message topic with bit-level encoding.

The payload structure is:

[Block1: 2 bytes][Block2: N bytes][Block3: 2 bytes][Block4: M bytes][Block5: 2 bytes][Block6: P bytes]

• The length blocks (odd-numbered) are 2-byte unsigned 16-bit integers indicating the byte length of the following data block.

• The data blocks (even-numbered) are UTF-8 encoded strings.

Block mapping:

Connecting to the broker with a ClearBlade auth token

Once the client is authenticated, the token can be extracted and the connection can be established.

Asymmetric Keys

A device must create a private/public key pair. The private key is only kept local on the device, while the public key is uploaded to the ClearBlade IoT Enterprise system's device record.

See Creating key pairs to create the key pair.

To authenticate, the device will construct a JSON Web Token (JWT) based on the private key and present that on the MQTT authentication or REST endpoint's connect packet. The JWT is used in place of the standard ClearBlade auth token.

• The device uses the private key to sign the JWT. The token is passed to ClearBlade IoT Core as proof of the device's identity.

• The service uses the device's public key (uploaded before the JWT is sent) to verify the device's identity.

To add the public key to the device:

1. Find the device in the system's device table.

2. Right-click the device's gear icon and choose Public Keys, then click the Add button.

3. Pick the appropriate key format. ClearBlade IoT Core supports RSA and elliptic curve algorithms. For details on key formats, see Public key format.

Claims

ClearBlade IoT Enterprise requires these reserved claim fields. They may appear in any order in the claim set.

The optional nbf (not before) claim will be ignored.

Example claim set:

{
  "aud": "my-project",
  "iat": 1509654401,
  "exp": 1612893233
}

Only devices are supported with this method.

Each time the client sends an MQTT message (including PINGREQ), the ClearBlade MQTT Broker checks the exp. If the current time is later than exp + 10m the client will be disconnected. The 10 minutes allows for time skew between client and server.

Basic Authentication

Basic Authentication is useful for limited devices that cannot generate JWTs or store tokens. The device connects as an MQTT client using these credentials:

• MQTT username = system_key_or_name:device_name

• MQTT password = device_active_key

Performance warning: Every connection using Basic Authentication triggers a full credential check against the platform — no token is cached or reused. This is significantly more CPU-intensive than token-based authentication. Avoid using Basic Auth for devices that reconnect frequently or in bulk; mass reconnection events can cause CPU spikes that affect all traffic on the instance.

Additional notes:

• The device does not receive a token upon successfully connecting. Authentication must be performed each time the device connects.

• Basic Authentication must first be explicitly enabled within an environment — contact ClearBlade Support to enable it.

mTLS

Devices may connect using an mTLS approach to gain their access token. ClearBlade handles mTLS auth and TLS termination.

The mTLS configuration will be valid for all systems running in the IoT Enterprise instance.

Currently, no user interface administration is available to manage the loaded certificates. All certificates must be loaded to the server via API calls.

Requirements

The device name must be the cn (common name) in the cert presented. The platform verifies that the certificate matches the device.

APIs

/admin/settings/mtls

GET, PUT (upsert), and DELETE support. Admin only.

PUT body required:

{"root_ca": "certificate in PEM format", "crl": "certificate revocation list in PEM format (optional)"}

Returns nil on success.

GET — no query support. Returns the latest mTLS settings in JSON.

DELETE — no query support. Deletes mTLS settings.

/admin/revoked_certs

GET, POST, and DELETE support. Admin only.

POST — use to revoke a certificate. Body required:

{"certificate_hash": "sha256 hash of the ASN.1 DER format of the certificate", "description": "optional"}

Returns nil on success.

GET — query supported. An empty query gets all revoked certificates.

DELETE — query supported. An empty query deletes all revoked certificates.

Authentication

A device can authenticate (receive a token) using mTLS by sending an HTTP POST request to port 444.

The returned response will contain a device token.

ALPN (Application Layer Protocol Negotiation)

ClearBlade supports mTLS authentication for devices connecting via MQTT using ALPN on port 444. The ALPN protocol name is clearblade_mqtt_mtls. Device Just-in-Time (JIT) provisioning is also supported. A Root CA certificate must be added via the mTLS admin endpoints before connecting devices via mTLS.

To connect to MQTT using mTLS, the device needs to set the following in the MQTT Connect packet:

1. The Username field must be a stringified JSON object with the device name set, and any other column values required for JIT provisioning. For example: {"name": "myDevice"}

2. The Password field must contain the system key.

Shared Access Token Signature

Devices may authenticate using a shared access token signature.

Requirements

The shared access token should follow the signature outlined here. The token should not include a shared access policy and the resource URI should have the following form: broker-domain/devices/system_key/device_name.

Devices using the Azure SDK can be configured to generate this token format by setting the connection string as follows:

HostName=yourdomain.clearblade.com;DeviceId=YourSystemKey/YourDeviceName;SharedAccessKey=YourKey

Note on DeviceId format: The DeviceId field uses a ClearBlade-specific format: YourSystemKey/YourDeviceName. This is not the standard Azure DeviceId — it encodes both the system key and device name separated by a forward slash.

The shared access key that the token is generated from must be uploaded to the platform using the following APIs.

APIs

/admin/devices/private_keys/SYSTEM_KEY/DEVICE_NAME

POST and DELETE support. Admin only.

POST body required:

{"key_type": "shared_access_token", "private_key": "contents of base64 encoded shared access token"}

Returns the key on success.

DELETE at: /admin/devices/private_keys/SYSTEM_KEY/DEVICE_NAME?id=key_id

Authentication

When sending a connect packet to the broker, the password must be the shared access token.