NOTE: This is an advanced topic and shouldn't normally affect how you use Overlock.

Overlock Agent Authentication

IoT node Authentication

Overlock Agents (running on IoT nodes) connects to the Overlock platform using an MQTT(s) connection. Overlock uses the normal username and password authentication to login, however the ways in which those components are used is somewhat unique in that Overlock supports on-the-fly device registration for new IoT devices. The aim of this is to make it as simple as possible to get new devices up and running on overlock.

MQTT authentication is primarily a username/password, however MQTT also has a client_id. For overlock, each of these has to be in the formats specified below. The overlock agent handels all of this internally.

section value
client_id hash("sha256", "<project_id>:<client_node_id>")
username v1:<project_id>:<client_product_name>:<client_node_id>
password p:<project_key> for the project_id provided

The client_id is there to prevent the same device connecting multiple times. A very simple scheme has been chosen for this in order that it will never need to change in the future.

The username contains the bulk of the authenticating details. Overlock partitions data based on Projects, so the project_id and a valid project_key are used to determine if this client is allowed to connect at all.

The client_product_name and the client_node_id are the developers references to those devices and will ideally match whatever the primary key for identifying types of IoT device and the id of IoT nodes in the developers system. This has been done so that messages in overlock may be easily cross-referenced where required.

The MQTT auth will perform the following steps:

  1. Check the project_id is valid (loads a project)
  2. Check the project_key is valid (matches the project and is not blacklisted)
  3. Check the client_node_id device has not been blacklisted (if it exists at all).

If the above steps are valid, then the device will be permitted to connect and if it's not been connected before it will have an entity created in Overlock for it.

The overlock system differs from other logging platforms in that it has per-device identifiers which permits far more granular blacklisting of devices which should not be allowed to connect to the system anymore when compared to systems like papertrail, sentry or most other logging platforms which have one set of global credentials.

Node Auto Creation

Nodes are automatically created in the Overlock platform from the details provided in the authentication. There are 2 situations where a new device may be seen:

  1. The device directly connects to the platform over MQTT
  2. The device is referenced by another node

In the former situation, we can use the client_product_name and the client_node_id to fetch or create a Product, as well as fetching or creating a Node.

For when a Node is referenced, Overlock only has access to the client_node_id (from the reference) which means that nodes cannot be assigned to a Product. In this case the Node will be created and assigned to a special "Unknown" Product, until such time that the device connects directly.

Other ways of creating Nodes

At present, Overlock only supports automatic node creation, however in future an API will be exposed which will allow creation of Nodes with device specific keys for even greater security and inclusion in the provisioning process of IoT devices.

The API will also include enhanced ability to set attributes and other rules for devices, as well as retriving configuration files for Nodes.