Murano Device Connectivity Overview
Murano IoT platform's device connectivity functionality controls how devices are identified and provisioned.
The sections below summarize and describe the feature set. In all the features below, the various configuration/settings parameters can be selected for both the Product UI as well as Murano CLI.
Communication and Authentication
This section covers the methods devices can utilize in order to communicate with Murano.
Devices connect to Murano using their unique product domain. This
fqdn (fully qualified domain name) can be found in the Product UI as well as via the Device2
getGatewaySettings API method.
A Murano device gateway can be configured to use different methods of authentication:
- Token (CIK)-based authentication
- Password-based authentication
- TLS Client Certificate authentication
When the Token method of authentication is selected, a device can provision a private authentication Token to be used in subsequent communications to uniquely identify and authenticate itself to the Murano device gateway. If provisioning is disabled, then device authentication Tokens must be managed via Murano CLI and UI tools and manually associated and stored on the device.
NOTE: An authentication option available with the Token method can disable the use of TLS connections, allowing unsecured HTTP communication between a device and the Murano device gateway. The use of this option is highly discouraged and maintained in Murano as a development tool for easing the validation and development of firmware on a device connecting to Murano.
When the Password method of authentication is selected, a device can provision credentials for the given Password (at least 20 characters) to be used in subsequent communications to identify and authenticate itself to the Murano device gateway. If provisioning is disabled, then device authentication Password must be managed via Murano CLI and UI tools and manually associated and stored on the device.
TLS Client Certificate Authentication
When the TLS Client Certificate method of authentication is selected, a device uses a unique X509 private and public key that Murano uses to both authorize and identify the connecting device. Murano will use the X509 credentials (which can be provided by a PKI vendor or it can be self-signed) to identify and authenticate the device. Certificate based authentication has two flavors:
Without certificate verification
This allows clients to connect to Murano with a certificate (self-signed or signed by a Certificate Authority). Murano will extract the common name
/CN=<value> from the certificate and use the
<value> to identify the client. Then, it will use the certificate as a password to verify the client's authenticity.
With certificate verification against a Certificate Authority (CA)
It is possible to enable and configure a Certificate Authority (CA) for a product under its Protocol settings. If CA is enabled and configured, the certificate presented by the client will be verified against the configured CA. If the configured CA was its issuer and certificate has not yet expired, authentication will be successful. Otherwise, authentication will fail. If CA has not been enabled or it has been disabled and a client connects with a certificate, authentication will fall back to the authentication "Without certificate verification" method.
Several features have been added and enhanced around the topic of device provisioning.
- Identity Format
- Presenter Identity
- IP Whitelisting
This feature defines how connecting devices must identify themselves or be considered invalid and ignored in successive communication attempts. Devices are identified differently based on the authentication method chosen—Token or TLS Client Certificate. In the case of Token authentication, the identity of the connecting device is determined by the
id field of the HTTP Device
activate API method. In the case of TLS Client Certificate authentication, the identity of the connecting device is determined by the common name
/CN value of the client certificate. In both of these methods, the Identity Format must be adhered to in order for the device to be recognized in communication requests.
The Presenter Identity configuration setting allows devices to identify and provision themselves at the time they first connect to Murano. The Presenter Identity setting simply means that devices connecting to a Murano device gateway do not need to have their identity be whitelisted in advance and that the Murano device gateway will auto-whitelist the identity the device "presents."
This setting is a boolean that, when set to
true (default), allows devices to provision themselves and any device identity to communicate with the Murano device gateway. When set to
false, devices connecting must first be whitelisted onto the device gateway in order for its requests to be honored.
IP Whitelisting can be used to restrict device provisioning. The IP whitelisting manages known IP addresses that devices will connect from when connecting to Murano for the first time. This feature is useful to IoT vendors working closely with hardware manufacturers. If a connecting device's requests originate from an IP address not in the configured whitelist, then the device will be ignored. Once the device has connected from an IP address in this whitelist, it can make successive requests from any other IP, and its requests will be honored.
This feature allows Murano Product administrators to revoke the communication privileges on a per-device basis. Marking a device as locked will cause all connection attempts by the device to be ignored. This can be useful, for example, in development or during in-field management to temporarily disable device communications.
When devices connect, disconnect, make provision attempts, and publish data, these events will be logged. The logging events are not saved, so they can only be viewed in real time either by the Logs section in the Product UI or Murano CLI. This is most useful in debugging and development applications.
Resource definitions have been updated to specify the available state fields of all devices connecting to the device gateway of a Murano Product. A Resource is identified by an
alias that has a data format (string, number, or boolean), and optionally a restricted set of allowed values and whether it is modifiable from "the cloud." Each device identity's state is maintained with the latest
set values for every resource.
Resources that are modifiable from "the cloud" have their
set value updated when non-device agents update the device state. Resources that are not modifiable from "the cloud" only have their state updated by the values the device reports. The term "the cloud" is a placeholder for any agent such as a mobile or web application that can be authorized to set the device state.
From the connecting device's perspective, there is no change. That is, getting a resource will get the current "set" value in the device's state. Anytime a device posts data to a resource, both "reported" and "set" values in the device's state are updated, whereas when "the cloud" uses the
setIdentityState API method, it only updates the "set" value.
The Content area is a simple file storage area that devices can download things like firmware updates and is unique to each Product.
For more information on the Murano device connectivity feature set, please refer to the resources below:
Q: How is Murano's Device Connectivity different than One Platform?
A: The following high-level features highlight some of the many improvements:
- Using TLS client certificates for authentication support the use of hardware crypto modules, providing an additional layer of security.
- Logging and debugging features like the ability to see the last device IP address, and a UI that has been written with the device developer in mind.
- Sub-second time resolution. A frequently requested feature for One Platform was the ability to write multiple values within a second. The new Murano device gateway supports this.
- A user interface for content/firmware management for connected devices.