Device Registration Guide For Installers

The SMDH IoT Device Registration User Guide is intended for device installers and organisations who need to stream data from their devices into MDEP using MQTT protocol. The process involves registering a device and downloading a public/private key pair and a certificate onto the device and installing these on the device.

Requesting Access

Complete the org admin process with your assigned Business Development Officer.

Request the SMDH device Installer role by emailing support@smdh.uk. Use the subject line: ‘Request for device installer role’ After these steps have been completed, you can proceed to registering your devices using either the SMDH IoT hub dashboard or the SMDH IoT device registration API.

Registering A Device Through The Dashboard

1. In your choice of browser navigate to https://iot.smdh.uk/ and login using your credentials by clicking on the Login button in the middle of the page.

2. Navigate to the registration page by clicking on the Register device button on the top right corner.

3. Fill in the device registration information, including the organisation and project names, and the device serial number. You can add up to 3 devices that belong to the same organisation and project in a single registration request. To add another device serial number simply click on the Add new device serial number button. Finally, submit the registration request by clicking on Register device(s).

4. Upon successful registration, a card will be added at the bottom for each registered device with the registration result, this includes the command to be used to obtain the secure connection kit zip file for that device.

5. Each result card for a device contains a command for obtaining the secure connection kit zip file. The use of this file and instructions to complete the registration process are further explained in the step Obtaining The Secure Keys and Certificates from the API registration method section below.

Registering A Device Through The API

1. Obtain a JWT from the API endpoint using the following sample command (remember to replace all <placeholders> from the actual command below such as username, password and client_secret):

   Note

   Contact support to obtain your client secret.

   Danger

   Your user password and the client secret are sensitive data. Make sure to safe guard these credentials. Avoid exposing your secret API token in places that are accessible to the public, such as GitHub or client-side code.

   wgetcurl

   wget --quiet \
   --method POST \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --body-data 'grant_type=password&client_id=iot-installer-client&client_secret=<client_secret>&scope=openid&username=<your_username>&password=<your_password>' \
   --output-document \
   - https://sso.smdh.uk/auth/realms/SMDH/protocol/openid-connect/token
   

   curl --request POST \
   --url <https://sso.smdh.uk/auth/realms/SMDH/protocol/openid-connect/token> \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data grant_type=password \
   --data client_id=iot-installer-client \
   --data client_secret=<client_secret> \
   --data scope=openid \
   --data username=<username> \
   --data password=<password>
   

   The response from the API endpoint would be as follows

   {
       "access_token": "<access_token>",
       "expires_in": 300,
       "refresh_expires_in": 1800,
       "refresh_token": "<refresh_token>",
       "token_type": "Bearer",
       "id_token": "<id_token>",
       "not-before-policy": 0,
       "session_state": "4dbdadaa-e956-487b-b647-ad9dac36a0bb",
       "scope": "openid profile email"
   }
   

2. Call the Device Registration API to register your device with the JWT token (access_token) obtained in step 3 above. You must also provide the following information:

   • Your Org name (use the exact name found in this list)
   • Your Project name (eg “Jobtracking”),
   • The Device Serial Number (Max length is 128 utf-8 bytes.)
   wgetcurl

   wget --quiet \
   --method POST \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <jwt_access_token>' \
   --body-data '{"org": "<your_org>","proj": "<your_proj>", "deviceSerialNumber": "<your_device_serial_number>"}' \
   --output-document \
   - https://y9pct0qwk6.execute-api.eu-west-1.amazonaws.com/Prod/registerDevice
   

   curl --request POST \
   --url <https://y9pct0qwk6.execute-api.eu-west-1.amazonaws.com/Prod/registerDevice> \
   --header 'Authorization: Bearer <jwt_access_token>' \
   --header 'Content-Type: application/json' \
   --data '{
   "org": "<your_org>",
   "proj": "<your_proj>",
   "deviceSerialNumber": "<your_device_serial_number>"
   }'
   

   The response back from the Registration API would be as follows:

   {
   "message": "Successfully registered device!",
   "data": {
       "org": "<your_org>",
       "project": "<your_proj>",
       "deviceSerialNumber": "<your_device_serial_number>",
       "cmd": "curl -v -H 'x-api-key:<api_key>' -H 'Accept-encoding: gzip, deflate, br' '<https://y9pct0qwk6.execute-api.eu-west-1.amazonaws.com/Prod/getcert?deviceSerialNumber=><your_device_serial_number>&org=<your_org>&proj=<your_proj>' -JL > /tmp/<rename_me>.zip"
   }
   }
   

   The highlighted value from the data.cmd element in the JSON response above is the command used to obtain the secure connection kit zip file for that device. The use of the files within this secure connect kit zip file is further explained in the section below.

3. Obtaining The Secure Keys and Certificates

   Execute the command from the previous steps on the actual device which is being registered to obtain the secure connection kit zip file from CVM cert download API which contains the secure keys and certs. This secure connection kit zip file also contains the config file (iot_config.json) containing the IoT endpoint and mqtt publish topic to which this registered device can send MQTT messages using mTLS. Sample contents below:

   {
       "config":{
           "iot_endpoint":"abc123def-ats.iot.eu-central-1.amazonaws.com",
           "publish_topic":"$aws/rules/S301/1/stfc---hartree-centre/test/test123"
       }
   }
   

   Warning

   Remember to only use QoS level 0 ie qos0 when configuring your mqtt client libraries.

   Next steps will be the same (BAU) as per the CVM User Guide for Sensor Installers (step 4/5 onwards in that document).

FAQs

If you have any questions, please do not hesitate to contact us, and if possible, keep everyone in the email loop to help us resolve common problems. Some common/frequently asked questions and answers are below.

Will this work for every device provider?

No. For other network device provisioning scenarios where we might NOT have the opportunity to install certificates (e.g., pre-boxed devices) at a firmware level, we will need to further explore the AWS recommended ‘claims-cert/token’ flow with the device providers to see what they can/can’t pre-install. They may also have their own CA/certificates that we could add to our trust-chain (TBD).

I forgot to copy the curl command for downloading the certificate. How do I obtain the command for the registered device?

Certificates cannot be reissued for existing devices. As such, a new device must be registered using a different serial number to get a new certificate. You may also label the old device as DEACTIVATED from the device details view, which will hide the device from the default devices list view.