Client device auth
The client device auth component (aws.greengrass.clientdevices.Auth) authenticates client devices
and authorizes client device actions.
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
This component has the following versions:
Client device auth version 2.3.0 has been discontinued. We strongly recommend that you
upgrade to client device auth version 2.3.1.
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:
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:
-
iot:Subscribe, where the resources include the ARNs of the following
MQTT topic filters:
-
iot:Receive, where the resources include the ARNs of the following
MQTT topics:
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:
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.3.1
-
The following table lists the dependencies for version 2.3.1 of this
component.
- 2.3.0
-
The following table lists the dependencies for version 2.3.0 of this
component.
- 2.2.3
-
The following table lists the dependencies for version 2.2.3 of this
component.
- 2.2.2
-
The following table lists the dependencies for version 2.2.2 of this
component.
- 2.2.1
-
The following table lists the dependencies for version 2.2.1 of this
component.
- 2.2.0
-
The following table lists the dependencies for version 2.2.0 of this
component.
- 2.1.0
-
The following table lists the dependencies for version 2.1.0 of this
component.
- 2.0.4
-
The following table lists the dependencies for version 2.0.4 of this
component.
- 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.
- 2.0.1
-
The following table lists the dependencies for version 2.0.1 of this
component.
- 2.0.0
-
The following table lists the dependencies for version 2.0.0 of this
component.
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.3.x
-
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:
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.
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:
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:publish – Grants permission to
publish MQTT messages to topics.
This operation supports the following resources:
-
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 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-
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:
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.
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:
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:publish – Grants permission to
publish MQTT messages to topics.
This operation supports the following resources:
-
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
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-
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:
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.
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:
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:publish – Grants permission to
publish MQTT messages to topics.
This operation supports the following resources:
-
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)
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-
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:
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.
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:
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:publish – Grants permission to
publish MQTT messages to topics.
This operation supports the following resources:
-
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.
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.
- Linux
-
/greengrass/v2/logs/greengrass.log
- Windows
-
C:\greengrass\v2\logs\greengrass.log
To view this component's logs
Changelog
The following table describes the changes in each version of the component.
|
Version
|
Changes
|
|
2.3.1
|
- Bug fixes and improvements
-
|
|
2.3.0
|
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.3.0
|
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
-
|
|
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
-
- 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
-
|
|
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.
|
