{"type":"doc","content":[{"type":"paragraph","content":[{"text":"ClearBlade IoT Enterprise supports public key (asymmetric) and mTLS device authentication types.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Public key (asymmetric) authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"See ","type":"text"},{"text":"Creating key pairs","type":"text","marks":[{"type":"link","attrs":{"href":"https://clearblade.atlassian.net/wiki/spaces/IC/pages/2202763333"}}]},{"text":" to create the key pair.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"To authenticate, the device will construct a ","type":"text"},{"text":"JSON Web Token (JWT)","type":"text","marks":[{"type":"link","attrs":{"href":"https://clearblade.atlassian.net/wiki/spaces/IC/pages/2202206402"}}]},{"text":" 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.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The service uses the device’s public key (uploaded before the JWT is sent) to verify the device's identity.","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"To add the public key to the device, use the following steps and example images:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Find the device in the system’s device table:","type":"text"},{"type":"hardBreak"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":736,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":1801,"alt":"image-20240206-171618.png","id":"0b4a9dd6-efd4-466c-8019-c0f6b9924812","collection":"contentId-2592014362","type":"file","height":530}}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Right-click the device’s gear icon and choose Public Keys, then click the Add button:","type":"text"},{"type":"hardBreak"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":366,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":472,"id":"e86bc177-913a-4ea2-a0b5-0d06d92ca501","collection":"contentId-2592014362","type":"file","height":333}}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":444,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":771,"id":"2716bdd4-00f4-411f-8080-7026ec0ebfa4","collection":"contentId-2592014362","type":"file","height":576}}]},{"type":"paragraph"}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pick the appropriate key format:","type":"text"},{"type":"hardBreak"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":490,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":930,"id":"9edd7e2c-565b-4dc8-bbe8-8a249e272cec","collection":"contentId-2592014362","type":"file","height":821}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"ClearBlade IoT Core supports the RSA and elliptic curve algorithms. For details on key formats, see ","type":"text"},{"text":"Public key format","type":"text","marks":[{"type":"link","attrs":{"href":"https://clearblade.atlassian.net/wiki/spaces/IC/pages/2201354241/Device+Security#Devicesecurity-Publickeyformat"}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Claims","type":"text"}]},{"type":"paragraph","content":[{"text":"ClearBlade IoT Enterprise requires these reserved claim fields. They may appear in any order in the claim set.","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"529a6089-5bed-4d75-af84-70cc2d39b656"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"Required for","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"iat","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"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).","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"MQTT, HTTP","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"exp","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each HTTP request must include a JWT, regardless of expiration time.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Clients in Network Time Protocol (NTP) capable devices can use the ","type":"text"},{"text":"Google Public NTP Server","type":"text","marks":[{"type":"link","attrs":{"href":"https://developers.google.com/time/"}}]},{"text":" to keep the device clock synchronized; the authentication requirement is to keep the clock synchronized with an up to 10-minute skew.","type":"text"}]}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"MQTT, HTTP","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"sk","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"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.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"MQTT, HTTP","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"uid","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"User ID: This must be a single string containing the deviceId.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"MQTT, HTTP","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[156.0]},"content":[{"type":"paragraph","content":[{"text":"ut","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[464.0]},"content":[{"type":"paragraph","content":[{"text":"User type: This must be an integer hard-coded to value 3.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"MQTT, HTTP","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"The optional ","type":"text"},{"text":"nbf","type":"text","marks":[{"type":"code"}]},{"text":"(not before) claim will be ignored.","type":"text"}]},{"type":"paragraph","content":[{"text":"A JSON representation of the required reserved fields in a ClearBlade IoT Core JWT claim set is shown below:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"aud\": \"my-project\",\n \"iat\": 1509654401,\n \"exp\": 1612893233\n}","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Only devices will be supported with this method.","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"1136fd9a-6226-4892-8d0a-a21fa6babed7"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"Client type","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"Client ID","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"Username field","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"var(--ds-background-accent-gray-subtlest, #F4F5F7)","rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"Password field","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"New ClearBlade client via JWT","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"Anything","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"-unused-","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[170.0]},"content":[{"type":"paragraph","content":[{"text":"JWT token with sk, uid, and ut claims","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Each time the client sends an MQTT message (including PINGREQ), the ClearBlade MQTT Broker checks the ","type":"text"},{"text":"exp","type":"text","marks":[{"type":"strong"}]},{"text":". If the current time is later than ","type":"text"},{"text":"exp","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"+ 10m","type":"text","marks":[{"type":"strong"}]},{"text":" then the client will disconnected. The 10 minutes is to allow for time skew between client and server.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"The ","type":"text"},{"type":"mediaInline","attrs":{"id":"3e1ac699-6d3a-4713-bd26-069240dc6152","collection":"contentId-2592014362"}},{"text":" Python file shows an example of generating a JWT for the MQTT client’s password.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"mTLS","type":"text"}]},{"type":"paragraph","content":[{"text":"Devices may connect using an mTLS approach to gain their access token. ClearBlade handles mTLS auth and TLS termination. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The mTLS configuration will be valid for all systems running in the IoT Enterprise instance. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Currently, no user interface administration is available to manage the loaded certificates. All certificates must be loaded to the server via API calls.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Requirements","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"APIs","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/admin/settings/mtls","type":"text"}]},{"type":"paragraph","content":[{"text":"GET, PUT (upsert), and DELETE support. Admin only.","type":"text"}]},{"type":"paragraph","content":[{"text":"PUT:","type":"text"}]},{"type":"paragraph","content":[{"text":"Body required:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\"root_ca\": \"certificate in PEM format. \", \"crl\": \"certificate revocation list in PEM format. \"}","type":"text"}]},{"type":"paragraph","content":[{"text":"Returns nil on success","type":"text"}]},{"type":"paragraph","content":[{"text":"GET:","type":"text"}]},{"type":"paragraph","content":[{"text":"No query support. Get the latest mTLS settings in JSON:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\"root_ca\": \"certificate in PEM format\", \"crl\": \"certificate revocation list in PEM format\"}","type":"text"}]},{"type":"paragraph","content":[{"text":"DELETE:","type":"text"}]},{"type":"paragraph","content":[{"text":"No query support. Deletes mTLS settings.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/admin/revoked_certs","type":"text"}]},{"type":"paragraph","content":[{"text":"GET, POST, and DELETE support. Admin only.","type":"text"}]},{"type":"paragraph","content":[{"text":"POST:","type":"text"}]},{"type":"paragraph","content":[{"text":"Use to revoke a certificate. Body required:","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n“certificate_hash”: \"sha256 hash of the ASN.1 DER format of the certificate \",\n\"description\": \n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Returns nil on success.","type":"text"}]},{"type":"paragraph","content":[{"text":"GET:","type":"text"}]},{"type":"paragraph","content":[{"text":"Query supported. An empty query gets all revoked certificates, including those that match the query.","type":"text"}]},{"type":"codeBlock","content":[{"text":"[\n{\"id\": , \"certificate_hash\": , \"timestamp\": },\n{\"id\": , \"certificate_hash\": , \"timestamp\": }\n]","type":"text"}]},{"type":"paragraph","content":[{"text":"DELETE:","type":"text"}]},{"type":"paragraph","content":[{"text":"Query supported. An empty query deletes all revoked certificates and returns nil on success.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authentication","type":"text"}]},{"type":"paragraph","content":[{"text":"A device can authenticate (i.e., receive a token) using mTLS by sending an HTTP POST request to port 444 of the relevant URL. ","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"The following curl can be used as an example:","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"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\"","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"The returned response will contain a device token.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Similarly, this Python code can be used as an example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"import requests\n\nurl = \"https://yourURL.com:444/api/v/4/devices/mtls/auth\"\nheaders = {\"Content-Type\": \"application/json\", \"Accept\": \"application/json\"}\ndata = '{\"system_key\": \"yourSystemkey\", \"name\": \"yourDeviceName\"}'\nresp = requests.post(url, headers=headers, data=data, verify=True, cert=(\"path/to/yourDeviceCert.pem\", \"path/to/yourDeviceKey.pem\"))\n\ndeviceToken = str(resp[\"deviceToken\"])","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ALPN (Application Layer Protocol Negotiation)","type":"text"}]},{"type":"paragraph","content":[{"text":"ClearBlade supports mTLS authentication for devices connecting via MQTT using ALPN on port 444. The ALPN protocol name is ","type":"text"},{"text":"clearblade_mqtt_mtls","type":"text","marks":[{"type":"code"}]},{"text":". Device Just-in-Time (JIT) provisioning is also supported. A Root CA certificate must be added via the mTLS admin endpoints before connecting devices via mTLS.","type":"text"}]},{"type":"paragraph","content":[{"text":"To connect to MQTT using mTLS, the device needs to set the following in the MQTT Connect packet:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The Username field must be a stringified JSON object with the device name set, amongst other column values, if required for JIT provisioning. For example: ","type":"text"},{"text":"'{\"name\": \"myDevice\"}'","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The Password field must contain the system key.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Here’s a Python example using the Paho MQTT client:","type":"text"}]},{"type":"codeBlock","content":[{"text":"from __future__ import print_function\nimport sys\nimport ssl\nimport time\nimport datetime\nimport logging, traceback\nimport paho.mqtt.client as mqtt\nIoT_protocol_name = \"clearblade_mqtt_mtls\"\ncb_iot_endpoint = \"\" # For example test.clearblade.com\ncert = \"\"\nprivate = \"\"\nusername = '{\"name\": \"device-1\"}'\npassword = \"\"\nlogger = logging.getLogger()\nlogger.setLevel(logging.DEBUG)\nhandler = logging.StreamHandler(sys.stdout)\nlog_format = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')\nhandler.setFormatter(log_format)\nlogger.addHandler(handler)\ndef ssl_alpn():\n try:\n #debug print opnessl version\n logger.info(\"open ssl version:{}\".format(ssl.OPENSSL_VERSION))\n ssl_context = ssl.create_default_context()\n ssl_context.set_alpn_protocols([IoT_protocol_name])\n ssl_context.load_cert_chain(certfile=cert, keyfile=private)\n return ssl_context\n except Exception as e:\n print(\"exception ssl_alpn()\")\n raise e\nif __name__ == '__main__':\n topic = \"test/date\"\n try:\n mqttc = mqtt.Client(client_id=\"\")\n ssl_context= ssl_alpn()\n mqttc.tls_set_context(context=ssl_context)\n mqttc.username_pw_set(username=username, password=password)\n logger.info(\"start connect\")\n mqttc.connect(cb_iot_endpoint, port=444)\n logger.info(\"connect success\")\n mqttc.loop_start()\n while True:\n now = datetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S')\n logger.info(\"try to publish:{}\".format(now))\n mqttc.publish(topic, now)\n time.sleep(1)\n except Exception as e:\n logger.error(\"exception main()\")\n logger.error(\"e obj:{}\".format(vars(e)))\n logger.error(\"message:{}\".format(e.message))\n traceback.print_exc(file=sys.stdout)","type":"text"}]}],"version":1}