To authenticate to ClearBlade IoT Core, each device must prepare a JSON Web Token (JWT, RFC 7519). JWTs are used for short-lived authentication between devices and the MQTT or HTTP bridges bridge. This page describes the ClearBlade IoT Core requirements for the JWT’s contents.
...
The JWT must be passed in the CONNECT message’s password field when creating an MQTT client. A JWT must be included in each HTTP request’s header when connecting over HTTP.
Creating JWTs
JWTs have three sections: a header, payload (containing a claim set), and signature sections. The header and payload are JSON objects, serialized to UTF-8 bytes, then encoded using base64url encoding. ClearBlade has strict JWT base64url encoding requirements, unlike Google.
...
JWT
RS256(RSASSA-PKCS1-v1_5 using SHA-256 RFC 7518 sec 3.3). This is expressed asRS256in the JWT header’salgfield in the JWT header.JWT
ES256(ECDSA using P-256 and SHA-256 RFC 7518 sec 3.4), defined in OpenSSL as the prime256v1 curve. This is expressed asES256in the JWT header’salgfield in the JWT header.
In addition to the signing algorithm, you must supply the JWT token format.
...
The JWT payload contains a claim set of claims, and it is signed using asymmetric keys. The JWT claim set includes information, such as the token’s target, the issuer, the issued token time, and the token’s lifetime. Like the JWT header, the JWT claim set is a JSON object used in calculating the signature.
...
ClearBlade IoT Core requires the following these reserved claim fields. They may appear in any order in the claim set.
Name | Description | Required for |
|---|---|---|
| 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 |
| 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.
|
|
|
| MQTT, HTTP | |
| Audience: This must be a single string containing the cloud project ID where the device is registered. The authentication will only be allowed with further analysis if the connection request matches this project ID. | MQTT |
| 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 (key icon) at the top-right of the ClearBlade Registry Details page. | HTTP |
| User ID: This must be a single string containing the deviceId. | HTTP |
| User type: This must be an integer hard-coded to value 3. | HTTP |
The nbf(not before) claim will be ignored and is optional.
...
The JSON Web Signature (JWS) specification guides the mechanics of generating the JWT signature generation mechanics. The signature’s input is this content’s byte array:
...
To compute the signature, sign the base64url-encoded header, base64-url encoded claim set, and a secret key (such as a rsa_private.pem file) using the algorithm you defined in the header. The signature is then base64url-encoded, and the result is resulting in the JWT. This example shows a JWT before base64url encoding:
...
| Code Block |
|---|
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q |
...
Expiration of JWTs
As described in Required claims, tokens Tokens have expiration dates. If a device is connected over MQTT and its token expires, it automatically disconnects from ClearBlade IoT Core. You can prevent the device from disconnecting by automatically refreshing its token.