Page Comparison

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

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

When creating an MQTT client, the JWT must be passed in the password field of the CONNECT message. When connecting over HTTP, a JWT must be included in the header of each HTTP request.

Creating JWTs

JWTs are composed of have three sections: a header, a payload (containing a claim set), and a signature. The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding.

...

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

JWT header

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

...

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

For Elliptic Curve keys:

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

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

Note: The JWT header is not the same as the differs from the HTTP header (if you're connecting over HTTP).

...

The JWT payload contains a set of claims, and it is signed using the asymmetric keys. The JWT claim set contains includes information about on the JWT, such as the target of the token, the issuer, the time the token was issued, and /or the token’s lifetime of the token. Like the JWT header, the JWT claim set is a JSON object and is used in calculating the calculation of the signature.

Required claims

...

The nbf("Not Before") claim will be ignored , and is not required.

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 mechanics of generating the signature for the JWT. The input for the signature is the byte array of the following content:

{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 an a rsa_private.pem file) using the algorithm you defined in the header. The signature is then base64url-encoded, and the result is the JWT. The following 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 the following:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteS1wcm9qZWN0IiwiZXhwIjoxNTA5NjUwODAxLCJpYXQiOjE1MDk2NTQ0MDF9.F4iKO0R0wvHkpCcQoyrYttdGxE5FLAgDhbTJQLEHIBPsbL2WkLxXB9IGbDESn9rE7oxn89PJFRtcLn7kJwvdQkQcsPxn2RQorvDAnvAi1w3k8gpxYWo2DYJlnsi7mxXDqSUCNm1UCLRCW68ssYJxYLSg7B1xGMgDADGyYPaIx1EdN4dDbh-WeDyLLa7a8iWVBXdbmy1H3fEuiAyxiZpk2ll7DcQ6ryyMrU2XadwEr9PDqbLe5SrlaJsQbFi8RIdlQJSo_DZGOoAlA5bYTDYXb-skm7qvoaH5uMtOUb0rjijYuuxhNZvZDaBerEaxgmmlO0nQgtn12KVKjmKlisG79Q

Refreshing JWTs

As described in required claims, tokens have expiration dates. If a device is connected over MQTT and its token expires, the device it automatically disconnects from ClearBlade IoT Core. You can prevent the device from disconnecting by automatically refreshing its token.