Onboarding to plgd hub

Device can be remotely accessed when it’s onboarded and connected to the plgd hub. The connection between the device and the hub is a secure CoAP over TCP/UDP connection. Combination of JWT token and Identity certificate guarantees zero trust security on this end-to-end integration.

To onboard the device to the plgd hub, following configuration data are needed:

• coapGatewayAddress - address of the plgd hub in the format <scheme>://<host>:<port>
• authorizationCode - OAuth2.0 authorization code, used to get the device JWT token
• authorizationProviderName - authorization provider which is used to authorize the device on the plgd hub
• hubID - id of the plgd hub
• certificateAuthorities - trusted certificates used to verify the authenticity of the plgd hub

The device onboarding process starts right after successful provisioning.

To enable device to cloud connectivity, following tasks need to be successfully completed:

• Certificate Authority configured so the device can successfully verify authenticity of the plgd hub
• ACLs are configured so the device authorizes incoming requests from the plgd hub
• The hub onboarding configuration is set so the device knows where to connect and how to authorize the connection

Certificates can be configured only in the provisioning state. More information about this process can be found here.

When device is in provisioning state we can add the certificate authority to the device through credentials resource with body:

{
  "creds": [
    {
      "subjectuuid": "plgd/hub ID",
      "credtype": 8,
      "credusage": "oic.sec.cred.trustca",
      "publicdata": {
        "data": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
        "encoding": "oic.sec.encoding.pem"
      }
    }
  ]
}

        {
  "creds": [
    {
      "subjectuuid": "plgd/hub ID",
      "credtype": 8,
      "credusage": "oic.sec.cred.trustca",
      "publicdata": {
        "data": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
        "encoding": "oic.sec.encoding.pem"
      }
    }
  ]
}
    

The update device credentials is done via POST method on the /oic/sec/cred resource:

As the device acts as a server, it uses the concepts of ACLs for the client authorization. More information about ACLs and how to configure them can be found here.

For Hub to device communication, the device needs to have the following ACLs configured:

{
  "aclist2": [
    {
      "permission": 31, // full access
      "resources": [
        {
          "wc": "*", // to update/get all resources
          "if": [ "*" ] // all interfaces
        },
        {
          "href": "/oc/con", // to update/get device name
          "if": [ "*" ] // all interfaces
        },
        {
          "href": "/oc/swu", // to update/get device firmware
          "if": [ "*" ] // all interfaces
        }
      ],
      "subject": { // type of subject is defined by body content
        "uuid": "hub-id" // Hub id
      }
    }
  ]
}

        {
  "aclist2": [
    {
      "permission": 31, // full access
      "resources": [
        {
          "wc": "*", // to update/get all resources
          "if": [ "*" ] // all interfaces
        },
        {
          "href": "/oc/con", // to update/get device name
          "if": [ "*" ] // all interfaces
        },
        {
          "href": "/oc/swu", // to update/get device firmware
          "if": [ "*" ] // all interfaces
        }
      ],
      "subject": { // type of subject is defined by body content
        "uuid": "hub-id" // Hub id
      }
    }
  ]
}
    

The update device ACL is done via POST method on the /oic/sec/acl2 resource:

Each device hosts the coapcloudconfresource where the hub onboarding configuration has to be set. Resource definition can be found here. Setting the resource with required values will trigger the onboarding process, which is in detail described here.

Connection to the plgd hub is secured using a X.509 certificate. If the device mutually authenticates with the cloud and what certificate is used depends on credentials which are available on the device. Following table gives you more information if mTLS can be enabled and which certificate is used for the connection.

If the plgd hub requires mTLS authentication, the device needs to have the identity/manufacturer certificate signed by the certificate authority which is known in the plgd hub.

Before the device can be provisioned, the authorization code must be acquired and device need to be owned. The authorization code is used to authorize the device on the plgd hub.

When device provisioning ends with fail state, the device is not registered on the plgd hub. The device needs to be provisioned again.

To offboard the device from the plgd hub, the device can be in the any state. Device can still exist in the plgd hub after the offboarding process, because deregistration can fail. In this case, the device need to be deleted from the plgd hub.

• https://docs.plgd.dev/docs/tutorials/acl/
• https://docs.plgd.dev/docs/tutorials/disaster-recovery-replica-set/
• https://docs.plgd.dev/docs/quickstart/remote-access/
• https://docs.plgd.dev/docs/services/device-provisioning-service/onboarding-device/
• https://docs.plgd.dev/docs/services/device-provisioning-service/device-provisioning-service/