Using JSON Web Tokens

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 bridge. This page describes the ClearBlade IoT Core requirements for the JWT’s contents.

ClearBlade IoT Core does not require a specific token generation method. Helper client libraries can be found on JWT.io.

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

The JWT's header, payload, and signature are concatenated with periods. As a result, a JWT typically takes this form:

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

JWT header

The JWT header consists of two fields that indicate the signing algorithm and token type. Both fields are mandatory, and each field has only one value. ClearBlade IoT Core supports these signing algorithms:

JWT RS256 (RSASSA-PKCS1-v1_5 using SHA-256 RFC 7518 sec 3.3). This is expressed as RS256 in the JWT header’s alg field.
JWT ES256 (ECDSA using P-256 and SHA-256 RFC 7518 sec 3.4), defined in OpenSSL as the prime256v1 curve. This is expressed as ES256 in the JWT header’s alg field.

In addition to the signing algorithm, you must supply the JWT token format.

The header’s JSON representation is as follows:

For RSA keys:

{ "alg": "RS256", "typ": "JWT" }

For elliptic curve keys:

{ "alg": "ES256", "typ": "JWT" }

The header’s algorithm must match at least one of the public keys registered for the device.

The JWT header differs from the HTTP header (if you're connecting over HTTP).

JWT claims

The JWT payload contains a claim set, 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.

Claims

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

Name	Description	Required for

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, in practice, the token’s minimum lifetime will be equal to the acceptable clock skew, even if set to one second. For example, if a device sets its JWT’s `exp` to 01:10:20 UTC and `skew` is 10 minutes (current setting in IoT Core), then the server will disconnect the device at 01:20:20 UTC. When connecting over HTTP, 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
`aud`	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
`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 (key icon) at the top-right of the ClearBlade Registry Details page.	HTTP
`uid`	User ID: This must be a single string containing the deviceId.	HTTP
`ut`	User type: This must be an integer hard-coded to value 3.	HTTP

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

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

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

JWT signature

The JSON Web Signature (JWS) specification guides the JWT signature generation mechanics. The signature’s input is this content’s byte array:

{Base64url encoded header}.{Base64url encoded claim set}

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, resulting in the JWT. This example shows a JWT before base64url encoding:

{"alg": "RS256", "typ": "JWT"}.{"aud": "my-project", "iat": 1509654401, "exp": 1612893233}.[signature bytes]

After the final encoding, the JWT looks like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q

Expiration of JWTs

Tokens have expiration dates. If a device is connected over MQTT and its token expires, it automatically disconnects from ClearBlade IoT Core.