The CloudPlugs platform has three types of credentials for maximum security.
- Prototype & 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 Prototype, 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 is always generated by the platform for all devices at the time of enrollment. Since the Prototypes are immediately enrolled when created by the user, their Plug-ID is instantly available. Production Things and Controllers receive their Plug-ID upon enrollment in the platform.
The activation/connection password is set differently for Prototypes, Production Things and Controllers.
- Prototype activation/connection passwords can be set to be the user’s CloudPlugs account password with the AUTH_MASTER variable as explained below, or they can be set through the Prototype’s Properties Console Permissions panel.
- The activation/connection passwords for Production Things and Controllers are generated by the platform at enrollment time.
Here is an example of a Plug-ID/connection password pair generated by the platform.
The next two subsections detail the Prototype and Production Thing credential information.
Prototypes are automatically assigned a Plug-ID when they are created.
The Prototype activation/connection password can be either the CloudPlugs account password or it can be set under Permissions in the Prototype’s General->Device Profile panel.
When using the CloudPlugs Connection Libraries, the user’s CloudPlugs account password can be used as the activation/connection password for the Prototype by setting the parameter AUTH_MASTER to true.
For Connection Libraries, the following parameters need to be set:
- AUTH_PLUGID = to the Prototype’s Plug-ID created by the platform.
- AUTH_PASS = to either the password set under Permissions of the Prototype or the CloudPlugs account password if AUTH_MASTER is true.*
- AUTH_MASTER = to true if you want to automatically use the CloudPlugs user account password. Otherwise, set it to false and use the password set under Permissions of the Prototype.
If you use a SmartPlug™, you must uncomment the respective lines and set the values as follows:
- prototype_id = to the device’s Plug-ID.
- prototype_pass = to the device’s password.
Production Things are different than Prototypes in that they are not created by the user, but they are created by the platform using the credentials (serial number, enroll and control passwords) entered in the Production Templates.
The platform generates the Plug-ID and the activation/connection password for each Thing with a serial number and enroll password in the Production Template. It 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, 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.