Device Provisioning
The Everyware Cloud Device Provisioning Service is used to enroll new devices into an account. Once successfully provisioned, the enrolled device will be added to the account Device Registry Service and will receive the configuration to connect to it so that it will eventually become a managed device.
Through the Provisioning Service, enrolment of devices can be managed centrally within Everyware Cloud so that policies can be enforced consistently across the fleet of all the devices with a manageable, scalable and secure process. Besides this, the capability to automate the process strengthens security and simplify logistic aspects even further.
Typical scenarios where the provisioning process is used include:
- Devices have to be enrolled into their account for the first time after being produced
- Already enrolled devices have to be moved to a distinct account
- The the current and the new accounts are in the same Everyware Cloud instance
- The the current and the new accounts are in distinct Everyware Cloud instances
General Architecture
At high level the provisioning process is divided in three stages:
- Device configuration
- Cloud configuration
- Connection and execution
Device configuration defines the parameters required to connect to the Provisioning Service; these are the only information shared between device and cloud. The cloud configuration defines the parameters required by the device to connect to its final operational account plus any additional configuration required by the specific use case. Device configuration and cloud account configuration can be executed independently by distinct actors in the process.
In a typical scenario, the device configuration is carried out by operations during the manufacturing or delivery phases while the cloud account configuration is carried out by device fleet managers. This process promotes the separation of concerns:
- The operations/delivery team does not need to have any access to the cloud platform
- The operations/delivery team does not need to know the final operational configuration of the device in the target account
- The device management team handles the final operational configuration of the device via Everyware Cloud
- Sharing of information is reduced to minimum
Provisioning Steps
First the device manager user creates a Provision Request in Everyware Cloud that matches the device to be provisioned, the provision request need to be in place when the device will initiate the provisioning process.
Then the operations user configures the Provisioned Device with the parameters required to connect to the Provisioning Service. The device is then ready to be deployed on the field by a deployment operator.
Creation fo the Provision Request and configuration of the device can be executed in any order. However, the connection from the device to the provisioning service will succeed only if there is a provisioning request matching.
The operator physically installs the hardware on site, optionally he configures the network parameters to enable the physical connection between the device and Everyware Cloud.
At startup the device connects to a well-known Provisioning Endpoint, the device sends a provisioning message to the platform initiating the provisioning flow.
Everyware Cloud validates the message received from the device, and searches for a Provision Request that matches the device. If the request is found, the Everyware Cloud sends the operational configuration to the device.
After all configurations are received and installed by the device, it disconnects from the Provision Service and reconnects to the the operational account configured for the device. An entry for the provisioned device is enlisted in the the Device Registry.
Provisioning Request
The provision request contains all of the information needed to provision a device. The provision request has to be created in the final (target) operational account of the device.
Field | Default | Description |
---|---|---|
Provision Target Client ID | Identifies the target device for which the provision request is created. This identifier must match the clientId that is used by a device for the initial connection to the provision broker. The clientId must be unique within an account (preferably within the whole platform), and must follow the naming convention defined by the MQTT v3.1 protocol specification; otherwise, it will be not recognized as a valid clientId and the provision request will be rejected | |
Provision Username | Defines the username that will be used by the device for the initial connection to the provision broker. A user will be created under the Everyware Cloud Provision account with the defined username, which must be unique across the Everyware Cloud platform. The username must be at least three characters long, and contain only alphanumeric characters and “-” or “_” as special characters; otherwise, the provision request will be rejected. For example, the MAC address of the device or its serial number can be used for a provision request that is specific for each device. Alternatively, an account holder can decide to ship all its devices with the same credentials for the provisioning broker; in that case, it can reuse the same username and password for all its provision requests. | |
Provision Password | Defines the password that will be used by the device for the initial connection to the provision broker. This password should be paired with the username provided in the provision request. | |
Confirm Provision Password | Confirmation of the Provision Password | |
Provisioned Broker URL | The MQTT endpoint the device has to connect to after the provisioning has been successfully completed. | |
Activates On | Current date | Sets a date that the provision request becomes valid. Prior to this date, a device may connect to a provision broker, but it will not be able to be provisioned. If this parameter is not defined, the current date is used. |
Expires On (optional) | Sets a date after which the provision request is no longer valid. Beyond this date, a device may connect to the provision broker, but it will not be able to be provisioned. This date must follow the activation date otherwise the provision request will not be created. If this parameter is not defined, the provision request will never expire. | |
Generate Activation Key (optional) | False | Defines whether or not the device must provide an activation key as part of its provisioning request message. This key is generated by the system and should be written into the device. This field enhances security particularly in cases where a customer uses devices that have the same factory-supplied username and password, as the device is then also required to provide the activation key. This key acts like an optional password and it may also be used when all devices use a different username and password. If this parameter is not defined, it is set to false and no activation key is generated. |
Reserve User | True | Defines whether or not the user created on the target account will be reserved to the specific DeviceConnection of the provisioned Device. See Device Registry documentation for more information about. |
Device Connection Coupling | Account Default | Sets the Device User connection couplig that will be assigned to the DeviceConnection of the provisioned Device. See Device Registry documentation for more information about. See: DeviceConnectionService configuration in the account Settings view > Account Settings tab. |
Vpn Access | False | If enabled the provisioning process grants the vp:connect permission to the user associated to the provisioned device and automatically configures the device VpnClientService with the proper credentials (username and password). |
Password Length | The max between 20 and the value defined in the CredentialService configuration in the account Settings view > Account Settings tab | Length of the password generated for the user. Note: The password here refers to the final user that will be used by the device to connect the provisioned account. |
Additional Device Configuration | A list of additional device configurations formatted as an XML document that will be provided to the device during the provisioning process. |
To create a provisioning request goto to the Provisioning view and click the Add button.
If an additional Device Configuration is provided, it will be merged with the one generated by the provisioning.
Re-issue a provisioning request
A provision request that is closed (i.e. either completed or failed and expired) cannot be re-used. If for any reason a device needs to be provisioned again, the previous request has to be deleted and a new request has to be created.
A device cannot have multiple distinct requests associated at the same time. If a provisioning request is in status CREATED then it can be modified otherwise it has to be deleted and created again.
Changing a provisioning request
Be careful when changing or deleting an active provision request since a device may be using it or about to be using it. A provision request is active during the time window defined by Activates On and Expires On timestamps.
Additional Configurations
Additional configurations are defined as XML documents using the device configuration format.
To obtain the XML definitions of the services:
- download the snapshot from the EC Admin Console and isolate the components and the properties that need to be configured for your use case
See section Configuration Snapshots for more details regarding how to download/upload a snapshot.
Additional Configuration Limitations
Some configurations are reserved to the provisioning process and will be overridden by the system even though set differently in the value of this field.
The following parameters of the MQTTDataTransport Service component will be overridden by the provisioning procees:
- broker-url
- topic.context.account-name
- clientId
- username
- password
For example to fully reconfigure the Kura/ESF Command Service the following XML document che be used:
<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
<configuration>
<!--
Fully reconfigure the command service
-->
<id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
<properties>
<property name="command.timeout" array="false" encrypted="false" type="Integer">
<value>60</value>
</property>
<property name="command.enable" array="false" encrypted="false" type="Boolean">
<value>false</value>
</property>
<property name="privileged.command.service.enable" array="false" encrypted="false" type="Boolean">
<value>false</value>
</property>
<property name="kura.service.pid" array="false" encrypted="false" type="String">
<value>org.eclipse.kura.cloud.app.command.CommandCloudApp</value>
</property>
<property name="service.pid" array="false" encrypted="false" type="String">
<value>org.eclipse.kura.cloud.app.command.CommandCloudApp</value>
</property>
</properties>
</configuration>
</configurations>
To reconfigure just the enablement of the command service just define the value of the "command.enable" property, all the other properties will be remain unchanged:
<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
<configuration>
<!--
Just enable the command service
-->
<id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
<properties>
<property name="command.enable" array="false" encrypted="false" type="Boolean">
<value>true</value>
</property>
</properties>
</configuration>
</configurations>
The following reconfigures the poll rate of the Diagnostic Service to 15min (900sec) and decrease the threshold of the tmpfs usage percentage to 80 and 90.
<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
<configuration>
<!--
Increase the poll interval to 15min (900sec), decrease the threshold of the tmpfs usage percentage to 80 and 90
-->
<id>com.eurotech.framework.diagnostics.DiagnosticsService</id>
<properties>
<property name="health.monitor.poll.rate" array="false" encrypted="false" type="Integer">
<value>900</value>
</property>
<property name="fs.usage.threshold.warning.tmpfs.dev" array="false" encrypted="false" type="Integer">
<value>80</value>
</property>
<property name="fs.usage.threshold.critical.tmpfs.dev" array="false" encrypted="false" type="Integer">
<value>90</value>
</property>
</properties>
</configuration>
</configurations>
Configurations can be concatenated in a list. The following is an example for both change the configuration of the Command Service and the Diagnostic service in the same provisioning request:
<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
<configuration>
<!--
Just enable the command service
-->
<id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
<properties>
<property name="command.enable" array="false" encrypted="false" type="Boolean">
<value>true</value>
</property>
</properties>
</configuration>
<configuration>
<!--
Increase the poll interval to 15min (900sec), decrease the threshold of the tmpfs usage percentage to 80 and 90
-->
<id>com.eurotech.framework.diagnostics.DiagnosticsService</id>
<properties>
<property name="health.monitor.poll.rate" array="false" encrypted="false" type="Integer">
<value>900</value>
</property>
<property name="fs.usage.threshold.warning.tmpfs.dev" array="false" encrypted="false" type="Integer">
<value>80</value>
</property>
<property name="fs.usage.threshold.critical.tmpfs.dev" array="false" encrypted="false" type="Integer">
<value>90</value>
</property>
</properties>
</configuration>
</configurations>
Provisioned Device
The first thing the provisioned device should do is connecting to the Provisioning Service. The parameters required by the device to establish the connection to the Provisioning Service in Everyware Cloud are:
- Provisioning account endpoint (MQTT)
- Provisioning account name
- Device client ID
- Device user Credentials
Setting these parameters require that the user has access to the device and its services.
Accessing an ESF Device
The way the device is accessed to execute the setup of the provisioning configuration depends upon in which phase of the lifecycle the device is.
If the device is in house and a physical access is available via LAN, a direct access through the Web Admin Console can be used. Check the ESF guide for more details about accessing ESF via the Admin Console.
If the device is already provisioned and connected to the cloud it can be reached via Everyware Cloud Admin Console using the Configuration tab in the Device view:
Otherwise, if the device is already provisioned and connected to the cloud and Everyware Cloud Remote Access functionality is active, a direct ssh connection can be established from the user PC/Laptop to the ESF device so that the ESF Web UI can be used to get direct access to the device.
Configure an ESF Device
For details regarding how to configure an ESF device to execute the provisioning, please refer to ESF Documentation.
Provisioning Account
The provision account is a per-instance, reserved account used by the Provisioning Service to execute the process; it is shared across all accounts of the Everyware Cloud instance.
The provisioning account is bound to an MQTT Endpoint that is the endpoint that the device must connect to in order to trigger the start of the provisioning process.
There are two information a device need to know in order to successfully contact the Provisioning Service:
- The provisioning account name
- The provisioning account endpoint (MQTT)
For a device to succeed connecting to the provision account, a provision request with the device data must already exist.
For security reasons, devices connected to the provisioning account have read and write permissions limited to the MQTT topics necessary for the provisioning process; no other message exchanges are allowed.
Account Administration
See the Administration guide for more details regarding activities required to setup and maintain the Provisioning Account.
Provisioning Execution
The process initiates when the device connects to the Provisioning Service. The service identifies if there is a valid Provisioning Request matching the device:
- Same client ID
- Same user identity and valid user credentials
- Connection falls within the time window defined by the Activates On, Expire On values
If a match is not found the connection is refused otherwise the status of the request is set to RUNNING and configuration data is sent down to the device. If everything is ok the status is set to COMPLETED and the provisioning process stops.
Status COMPLETED means that no issue was detected by Everyware Cloud while executing the request. However, device side something may have gone wrong anyway when applying the new configurations and/or reconnecting to the final destination.
Upon request execution a new user will be created if not present in the target account so that each device is assigned its own identity for enforcement of authentication and authorisation; the system will automatically grant broker:connect permissions to this user.
When the request completes successfully the device must disconnect from the Provisioning Service and use the new configurations received to establish the connection to its target operational account.
If an error was detected by the Provisioning Service, the request status is set to FAILED. A device can retry a failed request until the request is valid., i.e. the expiration time is reached. Once this happens the provisioning process stops.
Each provisioning attempt, either successful or failed, is tracked by a provisioning execution. Provisioning executions can be reviewed from the Admin Console or via the RESTful API. From the Provisioning view select the provisioning request and then the Executions tab.
A provision request can have multiple provisioning executions each one corresponding to a provisioning attempt. The execution attempts stop either when the provisioning is successful or when the time window expires (i.e. the Expires On date is passed).
Execute a Job on Provisioning
There is a simple procedure for executing a Job on a device as soon as it connects to the target account after the provisioning process is completed.
- In the Devices view create the device with the correct clientID
- In the Batch Jobs view
- Create a Job
- Add the device to job targets
- Add the steps to be executed on the device (multiple steps can be added)
- Add the schedule selecting
- "Device Connect" if the job has to be executed when device connects after being provisioned
- "Interval Job" or "Cron Job" if the job has to be executed in a defined time schedule after the provisioning
- In the provisioning view create the provision request for the device
- Configure the device in provisioning mode
Once the device is provisioned, it will reconnect to the target account where the Job will be activated by the device connection event (if schedule is "Device Connect") or by the other schedules defined.
Troubleshooting
Check Provisioning Executions
If a provision request did not succeed, its execution log can be inspected to identify the causes of the error. In the Provisioning view select the failed request, from the executions tab select the execution and then click the Show Log button.
Target (mis)configurations
A recurrent reason for a device not being able to connect to its operational account is the misconfiguration of the target account MQTT endpoint. This mistake may be committed easier when the endpoint is set through the RESTful API where there is no drop-down menu to help the choice.
By misconfiguring the target account MQTT endpoint the device will likely become unreachable from the cloud.
Cloud unreachable
Check that the endpoints involved in the process are reachable by the device. Sometimes, if the device is behind a firewall or proxy, there might be limits for outgoing connections. MQTT usually use the ports 8883 for encrypted communications and 1883 for plain text communications but they can vary depending on the specific deployment.
If the provisioning MQTT endpoint or the the target account MQTT endpoint are unreachable by the device the provisioning process cannot take place or the connection to the operational account will fail.
Additional configs invalid
An invalid or inconsistent additional configuration can cause errors that will harm the device and prevent it to reconnect to its target operational account after the provisioning have been executed.
Verify and test every configuration that will be sent to the device.
Updated 24 days ago