Versions Type Operating system Requirements Dependencies Configuration Local log file Changelog

Client device auth

The client device auth component (aws.greengrass.clientdevices.Auth) authenticates client devices and authorizes client device actions.

Note

Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see Interact with local IoT devices.

Versions

Note

Client device auth version 2.3.0 has been discontinued. We strongly recommend that you upgrade to client device auth version 2.3.1 or later.

This component has the following versions:

2.4.x
2.3.x
2.2.x
2.1.x
2.0.x

Type

This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

This component uses the same log file as the Greengrass nucleus. For more information, see Monitor AWS IoT Greengrass logs.

For more information, see Component types.

Operating system

This component can be installed on core devices that run the following operating systems:

Linux
Windows

Requirements

This component has the following requirements:

The Greengrass service role must be associated to your AWS account and allow the iot:DescribeCertificate permission.
The core device's AWS IoT policy must allow the following permissions:
- greengrass:GetConnectivityInfo, where the resources include the ARN of the core device that runs this component
- greengrass:VerifyClientDeviceIoTCertificateAssociation, where the resources include the Amazon Resource Name (ARN) of each client device that connects to the core device
- greengrass:VerifyClientDeviceIdentity
- greengrass:PutCertificateAuthorities
- iot:Publish, where the resources include the ARN of the following MQTT topic:
  - $aws/things/coreDeviceThingName*-gci/shadow/get
- iot:Subscribe, where the resources include the ARNs of the following MQTT topic filters:
  - $aws/things/coreDeviceThingName*-gci/shadow/update/delta
  - $aws/things/coreDeviceThingName*-gci/shadow/get/accepted
- iot:Receive, where the resources include the ARNs of the following MQTT topics:
  - $aws/things/coreDeviceThingName*-gci/shadow/update/delta
  - $aws/things/coreDeviceThingName*-gci/shadow/get/accepted
For more information, see AWS IoT policies for data plane operations and Minimal AWS IoT policy to support client devices.
(Optional) To use offline authentication, the AWS Identity and Access Management (IAM) role used by the AWS IoT Greengrass service must contain the following permission:
- greengrass:ListClientDevicesAssociatedWithCoreDevice to enable the core device to list clients for offline authentication.

Endpoints and ports

This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see Allow device traffic through a proxy or firewall.

Endpoint	Port	Required	Description
`iot.region.amazonaws.com`	443	Yes	Used to get information about AWS IoT thing certificates.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.4.3

The following table lists the dependencies for version 2.4.3 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.12.0	Soft

2.4.1 and 2.4.2

The following table lists the dependencies for version 2.4.1 and 2.4.2 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.11.0	Soft

2.3.0 – 2.4.0

The following table lists the dependencies for versions 2.3.0 to 2.4.0 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.10.0	Soft

2.3.0

The following table lists the dependencies for version 2.3.0 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.10.0	Soft

2.2.3

The following table lists the dependencies for version 2.2.3 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <=2.9.0	Soft

2.2.2

The following table lists the dependencies for version 2.2.2 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <=2.8.0	Soft

2.2.1

The following table lists the dependencies for version 2.2.1 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.8.0	Soft

2.2.0

The following table lists the dependencies for version 2.2.0 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.6.0 <2.7.0	Soft

2.1.0

The following table lists the dependencies for version 2.1.0 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.2.0 <2.7.0	Soft

2.0.4

The following table lists the dependencies for version 2.0.4 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.2.0 <2.6.0	Soft

2.0.2 and 2.0.3

The following table lists the dependencies for versions 2.0.2 and 2.0.3 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.2.0 <2.5.0	Soft

2.0.1

The following table lists the dependencies for version 2.0.1 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.2.0 <2.4.0	Soft

2.0.0

The following table lists the dependencies for version 2.0.0 of this component.

Dependency	Compatible versions	Dependency type
Greengrass nucleus	>=2.2.0 <2.3.0	Soft

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

v2.4.2

deviceGroups

Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define client device authorization policies that specify the permissions for each device group.

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

The device groups for this core device. Each definition specifies a selection rule to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.

Each selection rule comprises at least one selection rule clause, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see AWS IoT fleet indexing query syntax in the AWS IoT Core Developer Guide.

Use the * wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.

Note

To select a value that contains a colon character (:), escape the colon with a backslash character (\). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify thingName: MyTeam\\:ClientDevice1 to select a thing whose name is MyTeam:ClientDevice1.

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.

This object contains the following information:

policyNameKey

The name of this authorization policy. Replace policyNameKey with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (mqtt:topic:mqttTopic) in a policy that specifies the mqtt:publish operation.

You can specify the * wildcard to allow access to all resources. You can't use the * wildcard to match partial resource identifiers. For example, you can specify "resources": "*", but you can't specify "resources": "mqtt:clientId:*".

statementDescription

(Optional) A description for this policy statement.

certificates

(Optional) The certificate configuration options for this core device. This object contains the following information:

serverCertificateValiditySeconds

(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.

This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the Moquette MQTT broker component, generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.

Default: 604800 (7 days)

Minimum value: 172800 (2 days)

Maximum value: 864000 (10 days)

performance

(Optional) The performance configuration options for this core device. This object contains the following information:

maxActiveAuthTokens

(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device, without reauthenticating them.

Default: 2500

cloudRequestQueueSize

(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.

Default: 100

maxConcurrentCloudRequests

(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.

Default: 1

certificateAuthority

(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority. This object contains the following information.

certificateUri: The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.
certificateChainUri: The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.
privateKeyUri: The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

security

(Optional) Security configuration options for this core device. This object contains the following information.

clientDeviceTrustDurationMinutes: The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

metrics

(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:

disableMetrics

If the disableMetrics field is set as true, the client device auth won't collect metrics.

Default: false

aggregatePeriodSeconds

The aggregation period in seconds that determines how often the client device auth aggregates metrics and sends them to the telemetry agent. This doesn't change how often metrics are published because the telemetry agent still publishes them once a day.

Default: 3600

startupTimeoutSeconds

(Optional) The maximum of time in seconds for the component to start. The component's state changes to BROKEN if it exceeds this timeout.

Default: 120

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

v2.4.0 - v2.4.1

deviceGroups

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

Note

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

This object contains the following information:

policyNameKey

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

statementDescription

(Optional) A description for this policy statement.

certificates

(Optional) The certificate configuration options for this core device. This object contains the following information:

serverCertificateValiditySeconds

Default: 604800 (7 days)

Minimum value: 172800 (2 days)

Maximum value: 864000 (10 days)

performance

(Optional) The performance configuration options for this core device. This object contains the following information:

maxActiveAuthTokens

Default: 2500

cloudRequestQueueSize

(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.

Default: 100

maxConcurrentCloudRequests

Default: 1

certificateAuthority

certificateUri: The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.
certificateChainUri: The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.
privateKeyUri: The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

security

(Optional) Security configuration options for this core device. This object contains the following information.

clientDeviceTrustDurationMinutes: The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

metrics

(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:

disableMetrics

If the disableMetrics field is set as true, the client device auth won't collect metrics.

Default: false

aggregatePeriodSeconds

Default: 3600

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

v2.3.x

deviceGroups

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

Note

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

This object contains the following information:

policyNameKey

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

statementDescription

(Optional) A description for this policy statement.

certificates

(Optional) The certificate configuration options for this core device. This object contains the following information:

serverCertificateValiditySeconds

Default: 604800 (7 days)

Minimum value: 172800 (2 days)

Maximum value: 864000 (10 days)

performance

(Optional) The performance configuration options for this core device. This object contains the following information:

maxActiveAuthTokens

Default: 2500

cloudRequestQueueSize

(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.

Default: 100

maxConcurrentCloudRequests

Default: 1

certificateAuthority

certificateUri: The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.
certificateChainUri: The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.
privateKeyUri: The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

security

(Optional) Security configuration options for this core device. This object contains the following information.

clientDeviceTrustDurationMinutes: The duration in minutes that the authentication information of a client device can be trusted before it is required to reauthenticate with the core device. The default value is 1.

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

v2.2.x

deviceGroups

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

Note

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

This object contains the following information:

policyNameKey

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

statementDescription

(Optional) A description for this policy statement.

certificates

(Optional) The certificate configuration options for this core device. This object contains the following information:

serverCertificateValiditySeconds

Default: 604800 (7 days)

Minimum value: 172800 (2 days)

Maximum value: 864000 (10 days)

performance

(Optional) The performance configuration options for this core device. This object contains the following information:

maxActiveAuthTokens

Default: 2500

cloudRequestQueueSize

(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.

Default: 100

maxConcurrentCloudRequests

Default: 1

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

v2.1.x

deviceGroups

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

Note

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

This object contains the following information:

policyNameKey

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

statementDescription

(Optional) A description for this policy statement.

certificates

(Optional) The certificate configuration options for this core device. This object contains the following information:

serverCertificateValiditySeconds

Default: 604800 (7 days)

Minimum value: 172800 (2 days)

Maximum value: 864000 (10 days)

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

v2.0.x

deviceGroups

This object contains the following information:

formatVersion

The format version for this configuration object.

Choose from the following options:

2021-03-05

definitions

This object contains the following information:

groupNameKey

The name of this device group. Replace groupNameKey with a name that helps you identify this device group.

This object contains the following information:

selectionRule

Note

You can specify the following selector:

thingName – The name of a client device's AWS IoT thing.

Example selection rule

The following selection rule matches client devices whose names are MyClientDevice1 or MyClientDevice2.


thingName: MyClientDevice1 OR thingName: MyClientDevice2

Example selection rule (use wildcards)

The following selection rule matches client devices whose names start with MyClientDevice.


thingName: MyClientDevice*

Example selection rule (match all devices)

The following selection rule matches all client devices.


thingName: *

policyName

The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the policies object.

policies

This object contains the following information:

policyNameKey

This object contains the following information:

statementNameKey

The name of this policy statement. Replace statementNameKey with a name that helps you identify this policy statement.

This object contains the following information:

operations

The list of operations to allow for the resources in this policy.

You can include any of the following operations:

mqtt:connect – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

This operation supports the following resources:
- mqtt:clientId:deviceClientId – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace deviceClientId with the client ID to use.
mqtt:publish – Grants permission to publish MQTT messages to topics.

This operation supports the following resources:
- mqtt:topic:mqttTopic – Restrict access based on the MQTT topic where a client device publishes a message. Replace mqttTopic with the topic to use.
  
  This resource doesn't support MQTT topic wildcards.
mqtt:subscribe – Grants permission to subscribe to MQTT topic filters to receive messages.

This operation supports the following resources:
- mqtt:topicfilter:mqttTopicFilter – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace mqttTopicFilter with the topic filter to use.
  
  This resource supports the + and # MQTT topic wildcards. For more information, see MQTT topics in the AWS IoT Core Developer Guide.
  
  The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the mqtt:topicfilter:client/+/status resource, the client device can subscribe to client/+/status but not client/client1/status.

You can specify the * wildcard to allow access to all actions.

resources

statementDescription

(Optional) A description for this policy statement.

Example: Configuration merge update (using a restrictive policy)

The following example configuration specifies to allow client devices whose names start with MyClientDevice to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}

Example: Configuration merge update (using a permissive policy)

The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.


{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}

Local log file

This component uses the same log file as the Greengrass nucleus component.

To view this component's logs

Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.
Linux
```
sudo tail -f /greengrass/v2/logs/greengrass.log
```
Windows (PowerShell)
```
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
```

Changelog

The following table describes the changes in each version of the component.

Version	Changes
2.4.3	Version updated for Greengrass nucleus version 2.11.0 release.
2.4.2	New features Adds a new `startupTimeoutSeconds` configuration option.
2.4.1	Version updated for Greengrass nucleus version 2.10.0 release.
2.4.0	New features Adds support for client device auth to emit operational metrics that will be published by the telemetry agent. Bug fixes and improvements Fixes an issue where the client device auth takes more than 10 seconds to verify a client device's identity. Additional minor fixes and improvements.
2.3.2	Bug fixes and improvements Adds support for caching hostname information so that the component correctly generates certificate subjects when restarted when offline.
2.3.1	Bug fixes and improvements Fixes a memory leak.
2.3.0	Warning This version is no longer available. The improvements in this version are available in later versions of this component. New features Adds support for offline authentication of client devices so that they can continue to connect to the core device when the core device isn't connected to the Internet. Adds support for customer-provided certificate authority that the core device uses as the root certificate to generate MQTT broker certificates.
2.2.3	Version updated for Greengrass nucleus version 2.8.0 release.
2.2.2	Bug fixes and improvements Fixes an issue where the local MQTT server certificate rotates more often than intended in certain scenarios.
2.2.1	Version updated for Greengrass nucleus version 2.7.0 release.
2.2.0	New features Adds support for custom components to call interprocess communication (IPC) operations to authenticate and authorize client devices. You can use these operations in a custom MQTT broker component, for example. For more information, see IPC: Authenticate and authorize client devices. Adds the `maxActiveAuthTokens`, `cloudQueueSize`, and `threadPoolSize` options that you can configure to tune how this component performs.
2.1.0	New features Adds the `serverCertificateValiditySeconds` option that you can configure to customize when the MQTT broker server certificate expires. You can configure the server certificate to expire after 2 to 10 days. Bug fixes and improvements Fixes issues with how this component handles configuration reset updates. Fixes an issue where the local MQTT server certificate rotates more often than intended in certain scenarios. To apply this fix, you must also use v2.1.0 or later of the Moquette MQTT broker component. Improves messages that this component logs when it rotates certificates. Version updated for Greengrass nucleus version 2.6.0 release.
2.0.4	Version updated for Greengrass nucleus version 2.5.0 release.
2.0.3	Bug fixes and improvements Credentials now refresh if you rotate the core device's private key. Updates to make log messages more clear.
2.0.2	Version updated for Greengrass nucleus version 2.4.0 release.
2.0.1	Version updated for Greengrass nucleus version 2.3.0 release.
2.0.0	Initial version.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Greengrass nucleus

CloudWatch metrics