Authenticate and authorize client devices

Use the client device auth IPC service to develop a custom local broker component where local IoT devices, such as client devices, can connect.

To use these IPC operations, include version 2.2.0 or later of the client device auth component as a dependency in your custom component. You can then use IPC operations in your custom components to do the following:

Minimum SDK versions

The following table lists the minimum versions of the Amazon IoT Device SDK that you must use to interact with the client device auth IPC service.

Authorization

To use the client device auth IPC service in a custom component, you must define authorization policies that allow your component to perform these operations. For information about defining authorization policies, see Authorize components to perform IPC operations.

Authorization policies for client device authentication and authorization have the following properties.

IPC service identifier: aws.greengrass.clientdevices.Auth

Authorization policy examples

You can reference the following authorization policy example to help you configure authorization policies for your components.

{
  "accessControl": {
    "aws.greengrass.clientdevices.Auth": {
      "com.example.MyLocalBrokerComponent:clientdevices:1": {
        "policyDescription": "Allows access to authenticate and authorize client devices.",
        "operations": [
          "aws.greengrass#VerifyClientDeviceIdentity",
          "aws.greengrass#GetClientDeviceAuthToken",
          "aws.greengrass#AuthorizeClientDeviceAction",
          "aws.greengrass#SubscribeToCertificateUpdates"
        ],
        "resources": [
          "*"
        ]
      }
    }
  }
}

VerifyClientDeviceIdentity

Verify the identity of a client device. This operation verifies whether the client device is a valid Amazon IoT thing.

Request

This operation's request has the following parameters:

Response

This operation's response has the following information:

GetClientDeviceAuthToken

Validates a client device's credentials and creates a session for the client device. This operation returns a session token that you can use in subsequent requests to authorize client device actions.

To successfully connect a client device, the client device auth component must grant the mqtt:connect permission for the client ID that the client device uses.

Request

This operation's request has the following parameters:

Response

This operation's response has the following information:

AuthorizeClientDeviceAction

Verify whether a client device has permission to perform an action on a resource. Client device authorization policies specify the permissions that client devices can perform while connected to a core device. You define client device authorization policies when you configure the client device auth component.

Request

This operation's request has the following parameters:

Response

This operation's response has the following information:

SubscribeToCertificateUpdates

Subscribe to receive the core device's new server certificate each time it rotates. When the server certificate rotates, brokers must reload using the new server certificate.

The client device auth component rotates server certificates every 7 days by default. You can configure the rotation interval to between 2 and 10 days.

This operation is a subscription operation where you subscribe to a stream of event messages. To use this operation, define a stream response handler with functions that handle event messages, errors, and stream closure. For more information, see Subscribe to IPC event streams.

Event message type: CertificateUpdateEvent

Request

This operation's request has the following parameters:

Response

This operation's response has the following information: