The CloudPlugs platform has three types of credentials for maximum security.
- Production Thing Activation/Connection Credentials.
- Controller Activation/Connection Credentials.
- Credentials required to generate Thing and Controller activation/connection credentials.
Every device, whether it is a Production Thing or a Controller needs a set of two credentials to communicate with CloudPlugs:
- AUTH_PLUGID – the device Plug-ID in the form dev-588acc123945ec8436bde3c.
- AUTH_PASS – the device activation/connection password.
The Plug-ID and activation/connection passwords for Production Things and Controllers are always generated by the platform for all devices at the time of enrollment.
Here is an example of a Plug-ID/connection password pair generated by the platform.
The next subsection details the Production Thing credential information.
Production Things are created by the platform using the credentials (serial number, enroll and control passwords) entered in the Production Templates.
CloudPlugs IoT uses the following Production Thing information to generate the Plug-ID and connectivity/activation password:
- Production Template Plug-ID (mod-xxxxxxxxxxxxxxxxxx).
- Serial number or hardware ID.
- Enroll password.
The following sections describe how to enroll and retrieve the Plug-ID and Connection Password in 3 different scenarios:
- Programmatically, when using Connection Libraries.
- Automatically, when using a SmartPlug™.
Using a Connection Library to connect a Production Thing requires the use of the proper method to handle the enrollment process as described in the documentation of the library selected. In all cases, the activation/connection password must be retrieved programmatically and input into the connectivity credentials. For example, if you are using the Java library, the description of the process can be found here.
When using Connection Libraries, the enrollment/activation process can be made also by writing an HTTP REST client that uses the method described in the Enroll a New Thing Developer Guide to retrieve the device’s Plug-ID and activation/connection password from the platform, and to use them to establish connection with the platform.
If a SmartPlug™ is used to connect to CloudPlugs IoT, it uses these parameters in its configuration file to automatically make the correct calls to CloudPlugs to:
- Enroll in the platform.
- Receive the Plug-ID and activation/connection password which it stores in its encrypted No-SQL database, and
- To activate in the platform.
To set the SmartPlug™ to do this, open the smartplug.conf file and uncomment and set the values of the following parameters:
- enroll_target = thing
- enroll_model = to the Plug-ID of the Production Template of the Thing.
- enroll_thing = to the serial number or hardware id of the Thing as configured in its Production Template.
- enroll_pass = to the enroll password configured in its Production Template.
- enroll_name = optionally set this value if you want to also give your thing a name. Otherwise, leave it commented.
It is possible to enroll a Production Thing manually. This method is only recommended when a SmartPlug™ is not used and it is not practical to write a program to retrieve the credentials. For example, if you need the credentials to enter them into the CloudPlugs MQTT broker configuration in the Edge One™ Message Router, this method can be a time saver.
To enroll a Production Thing manually:
- Open the Production Template of the Thing to be enrolled.
- Open the Serial Numbers tab.
- Select the serial number of the Thing to be enrolled.
- Press the CTRL key and double click.
- The Plug-ID and Connection Password of the device will be printed on the screen and the device’s status will become Enrolled.
- Copy the Plug-ID and Connection password to use them as connection credentials.
Much like Production Things, Controllers (which are control applications for Production Things), are not created by a user in the platform. Controllers are created by the platform when they enroll with the right credentials. When the Controller is properly authenticated for enrollment, the platform assigns to them a Plug-ID and activation/connection password. The credentials required for a Controller to enroll are:
- The Plug-ID of the Production Template of the Thing it will control.
- The serial number of the Thing it will control as set in the Thing’s Production Template.
- The Control password of the Thing it will control as set in the Thing’s Production Template.
The other parameters that can be set for a Controller such as name, controller serial number, user name and user password for the control application are not used by the platform to generate its main credentials.