Edge JWT authentication

A ClearBlade Edge can authenticate and connect to a ClearBlade platform using a JSON Web Token that it generates.

Prerequisites

1. Have an edge already in the platform system:

2. Config TOML to the edge binary (i.e., on the gateway device where the edge binary will run).

3. An RS256 public/private key pair is generated using these commands:

openssl genrsa -out jwtRSA256-private.pem 2048 openssl rsa -in jwtRSA256-private.pem -pubout -outform PEM -out jwtRSA256-public.pem

The private key will stay with the edge (i.e., on the gateway device where the edge binary will run). As explained in subsequent steps, the public key will be uploaded to the platform system.

4. Have a ClearBlade developer token (ClearBlade-DevToken) for use with the edge public key endpoint. This token can be obtained from Account Settings accessed from the top-right of the ClearBlade console:

Edge public key endpoint

This endpoint can be used to enable uploading, retrieving, and changing edge public keys. It is only available to developers.

/admin/edges/public_key/{systemKey}/{name}

GET: Gets all edges. No query parameters are supported.

POST: Adds a public key to an edge. Needs a JSON body in this format:

{
"public_key": <string> // required
"allow_expired": <bool> // optional
"expiration_time": <string> // optional
}

PUT: Change an existing edge public key. It needs a query and JSON body in this format:

{
"id": <string> // required
"$set": {
      "public_key": <string> // required
      "allow_expired": <bool> // optional
      "expiration_time": <string> // optional
  }
}

DELETE: Needs a query

Example curl to add a public key to an edge (credentials obfuscated):

curl -X POST 'https://platform.clearblade.com/admin/edges/public_key/d8e7d3c4012345678908aba599a301/myEdge' -H 'ClearBlade-DevToken: 1234567890JIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOi0xLCJpYXQiOjE3MDQ5MjE0MjQsInNpZCI6IjkxZmE4MWJjLTAyMDMtNDgzYS05NzYyLTJmYjRlNGM4MGViOSIsInR0IjoxLCJ1aWQiOiJiMjk3ODdlMDBiZDJkM2M0YzVjMmEwOTM4ZDEyIiwidXQiOjF9.gxaNLYzYPSSYX2joZ_AWMO4qpb0Wm523L1234567890' -H 'Content-Type: application/json' -d '{ "public_key": "-----BEGIN PUBLIC KEY-----\n1234567890kqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5P0Z4OUD5P1234567890\n1234567890XamIgWAwvnAs/oDRVqEejE2nwDhnpykaCGLkuDEN0LPd1234567890\nY3YvkJh71IkjuAjMZQ+00CXdezfCjmTtEpMCNA3cV+G1g6uIcdEpHKs0YHfC9CFQ\nrjkc7tl3idmcQLngIov/gsFY7D1pbOgkCVVcZCRLgsdFfhCUYwYCvdEVJP3w+5mG\nybvmhNRbbFG7eG3+hmZoOg0h3f6r2fqgSx6l0+Z3D77SRT6lBEHvGDlxb08ASeuE\n0SJAc6PdAKd3FDqdZok4z1qJsgMqtU/ZGJJG54pNECWmhoOar+aQm1234567890n\nEwIDAQAB\n-----END PUBLIC KEY-----" }'

The public key has been edited to fit on one line with \n characters.

A ClearBlade Edge is authenticated with a system using an edge cookie copied from the system’s edge settings and hardcoded into the edge’s configuration TOML or passed to the edge binary on startup as a flag.

As of platform version 9.33.0, edges can authenticate and connect using a JWT they generate. To enable JWT authentication, the following steps are needed:

Upload a public key to an existing edge by sending a POST request to the edge public key endpoint.
Modify the [Edge] section of the configuration TOML as follows:
1. Remove (or comment out) EdgeCookie.
2. Add these:
  UseJWTAuth = true
  PrivateKeyPath = <path_to_rsa_private_key_file>

Run the edge using edge -config=yourEdgeConfig.toml. The edge should run, authenticate, and connect to the platform.