Skip to main content
Skip table of contents

Certificate based authentication

ClearBlade IoT Enterprise supports public key (asymmetric) and mTLS device authentication types.

Public key (asymmetric) authentication

A device must create a private/public key pair. The private key is only left 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, use the following steps and example images:

  1. Find the device in the system’s device table:

    image-20240206-171618.png

  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 the 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.

Name

Description

Required for

iat

Issued at: The timestamp when the token was created, specified as seconds since 00:00:00 UTC, January 1, 1970. The server may report an error if this timestamp is too far in the past or future (allowing 10 minutes for skew).

MQTT, HTTP

exp

Expiration: The timestamp when the token stops being valid, specified as seconds since 00:00:00 UTC, January 1, 1970. The token’s maximum lifetime is 24 hours + skew.

  • The server will close all MQTT connections a few seconds after the token expires (allowing for skew) because MQTT cannot refresh credentials. A new token must be minted to reconnect. Because of the allowed skew, the token’s minimum lifetime will be equal to the acceptable clock skew.

  • Each HTTP request must include a JWT, regardless of expiration time.

  • Clients in Network Time Protocol (NTP) capable devices can use the Google Public NTP Server to keep the device clock synchronized; the authentication requirement is to keep the clock synchronized with an up to 10-minute skew.

MQTT, HTTP

sk

System key: This must be a single string containing the ClearBlade registry’s system key. This can be obtained by clicking the API keys button at the top-right of the ClearBlade Registry Details page.

MQTT, HTTP

uid

User ID: This must be a single string containing the deviceId.

MQTT, HTTP

ut

User type: This must be an integer hard-coded to value 3.

MQTT, HTTP

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

A JSON representation of the required reserved fields in a ClearBlade IoT Core JWT claim set is shown below:

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

Only devices will be supported with this method.

Client type

Client ID

Username field

Password field

New ClearBlade client via JWT

Anything

-unused-

JWT token with sk, uid, and ut claims

The generateJWT.py Python file shows an example of generating a JWT for the MQTT client’s password.

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 passed in is for the device.

Flow

1. mTLS request comes into HAProxy. The request body contains the device name, system key, and other data.

2. HAProxy forwards the request to ClearBlade without TLS termination.

3. A separate ClearBlade TLS server will perform mTLS auth. If no root CA cert is set, the auth fails.

4. The TLS server will check if the supplied client certificate is revoked or in a CRL.

5. If the check is successful, the Cb-Mtls-Vertified and X-Client-Certificate headers are added to the request and forwarded to the router.

6. ClearBlade returns an auth token after checking the headers and request body.

7. The auth token returns should be used in normal MQTT connect flow or REST header requests.

If the device does not exist in the system, it will be created if mTLS auth is successful.

APIs

/admin/settings/mtls

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

PUT:

Body required:

CODE
{"root_ca": "certificate in PEM format. <required>", "crl": "certificate revocation list in PEM format. <optional>"}

Returns nil on success

GET:

No query support. Get the latest mTLS settings in JSON:

CODE
{"root_ca": "certificate in PEM format", "crl": "certificate revocation list in PEM format"}

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:

CODE
{
“certificate_hash”: "sha256 hash of the ASN.1 DER format of the certificate <required>",
"description": <optional>
}

Returns nil on success.

GET:

Query supported. An empty query gets all revoked certificates, including those that match the query.

CODE
[
{"id": <id1>, "certificate_hash": <certificate1_hash>, "timestamp": <timestamp1>},
{"id": <id2>, "certificate_hash": <certificate2_hash>, "timestamp": <timestamp2>}
]

DELETE:

Query supported. An empty query deletes all revoked certificates and returns nil on success.

Authentication

A device can authenticate (i.e., receive a token) using mTLS by sending an HTTP POST request to port 444 of the relevant URL.

The following curl can be used as an example:

curl -X POST "https://yourURL.com:444/api/v/4/devices/mtls/auth" -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{"system_key": "yourSystemKey", "name": "yourDeviceName"}' --cert "path/to/yourDeviceCert.pem" --key "path/to/yourDeviceKey.pem"

The returned response will contain a device token.

Similarly, this Python code can be used as an example:

CODE
import requests

url = "https://yourURL.com:444/api/v/4/devices/mtls/auth"
headers = {"Content-Type": "application/json", "Accept": "application/json"}
data = '{"system_key": "yourSystemkey", "name": "yourDeviceName"}'
resp = requests.post(url, headers=headers, data=data, verify=True, cert=("path/to/yourDeviceCert.pem", "path/to/yourDeviceKey.pem"))

deviceToken = str(resp["deviceToken"])
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.