Advanced security

At coap-gateway you can set up mutual TLS, which verify the signature of the identity certificate of the device via configuration:

api:
  coap:
    tls:
      # default
      clientCertificateRequired: true

        api:
  coap:
    tls:
      # default
      clientCertificateRequired: true
    

After that, only devices which have signed identity certificates by CA configured in coap-gateway can access the hub.

When the device makes one of the calls sign up, sign in, sign out or sign off, coap-gateway needs to resolve the device ID.

1. If coap-gateway has set api.coap.authorization.deviceIDClaim then it will be resolved from JWT token. If JWT token doesn’t contain https://<YOUR_DOMAIN>/deviceId it returns code Unauthorized and closes the connection.
2. If coap-gateway has set mutual TLS api.coap.tls.clientCertificateRequired then it will be resolved from the device identity certificate.
3. If none of the previous options are set, device ID will be resolved from the request parameter.

When api.coap.tls.clientCertificateRequired and api.coap.authorization.deviceIDClaim are set, coap-gateway matches deviceID from certificate and JWT token. If they are not the same, then coap-gateway returns code Unauthorized and closes the connection.

First, you need to create a rule at Auth pipeline->Rules with code:

function (user, context, callback) {
  var deviceIdClaim = 'https://<YOUR_DOMAIN>/deviceId';
  var deviceId = (context && context.request && context.request.query && context.request.query.device_id) || null;
  if (deviceId) {
    context.accessToken[deviceIdClaim] = deviceId;
  }
  return callback(null, user, context);
}

        function (user, context, callback) {
  var deviceIdClaim = 'https://<YOUR_DOMAIN>/deviceId';
  var deviceId = (context && context.request && context.request.query && context.request.query.device_id) || null;
  if (deviceId) {
    context.accessToken[deviceIdClaim] = deviceId;
  }
  return callback(null, user, context);
}
    

After that, if you call authorize endpoint to obtain authorization code for a device with query parameter device_id=<deviceId>, and the device makes sign up with that code, the returned JWT access token will contain deviceId claim like https://<YOUR_DOMAIN>/deviceId: <deviceId>.

For validation of device ID claim by coap-gateway the api.coap.authorization.deviceIDClaim must be set to https://<YOUR_DOMAIN>/deviceId.

• https://docs.plgd.dev/docs/tutorials/developing-dashboard/
• https://docs.plgd.dev/docs/tutorials/testing/
• https://docs.plgd.dev/docs/tutorials/dashboard-branding/
• https://docs.plgd.dev/docs/tutorials/change-provision-status/
• https://docs.plgd.dev/docs/tutorials/laptop-deployment/