本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 客户端设备身份验证
<a name="client-device-auth-component"></a>

客户端设备身份验证组件（`aws.greengrass.clientdevices.Auth`）对客户端设备进行身份验证并授权客户端设备操作。

**注意**  <a name="client-device-component-context"></a>
客户端设备是本地 IoT 设备，连接到 Greengrass 核心设备以发送 MQTT 消息和数据进行处理。有关更多信息，请参阅 [与本地 IoT 设备交互](interact-with-local-iot-devices.md)。

**Topics**
+ [版本](#client-device-auth-component-versions)
+ [Type](#client-device-auth-component-type)
+ [操作系统](#client-device-auth-component-os-support)
+ [要求](#client-device-auth-component-requirements)
+ [依赖项](#client-device-auth-component-dependencies)
+ [配置](#client-device-auth-component-configuration)
+ [本地日志文件](#client-device-auth-component-log-file)
+ [更改日志](#client-device-auth-component-changelog)

## 版本
<a name="client-device-auth-component-versions"></a>

**注意**  
客户端设备身份验证版本 2.3.0 已停用。我们强烈建议您升级到客户端设备身份验证版本 2.3.1 或更高版本。

此组件具有以下版本：
+ 2.5.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type
<a name="client-device-auth-component-type"></a>

<a name="public-component-type-plugin-para1"></a>此组件是一个插件组件 (`aws.greengrass.plugin`)。[Greengrass Nucleus](greengrass-nucleus-component.md) 在与该 Nucleus 相同的 Java 虚拟机（JVM）中运行该组件。当您在核心设备上更改此组件的版本时，Nucleus 会重新启动。

<a name="public-component-type-plugin-para2"></a>此组件使用与 Greengrass Nucleus 相同的日志文件。有关更多信息，请参阅 [监控 AWS IoT Greengrass 日志](monitor-logs.md)。

<a name="public-component-type-more-information"></a>有关更多信息，请参阅 [组件类型](develop-greengrass-components.md#component-types)。

## 操作系统
<a name="client-device-auth-component-os-support"></a>

此组件可以安装在运行以下操作系统的核心设备上：
+ Linux
+ Windows

## 要求
<a name="client-device-auth-component-requirements"></a>

此组件具有以下要求：
+ [Greengrass 服务](greengrass-service-role.md)角色必须与您的关联并允许 AWS 账户 该权限。`iot:DescribeCertificate`
+ 核心设备的 AWS IoT 策略必须允许以下权限：
  + `greengrass:GetConnectivityInfo`，其中资源包括运行该组件的核心设备的 ARN
  + `greengrass:VerifyClientDeviceIoTCertificateAssociation`，其中资源包括连接到核心设备的每台客户端设备的 Amazon 资源名称（ARN）
  + `greengrass:VerifyClientDeviceIdentity`
  + `greengrass:PutCertificateAuthorities`
  + `iot:Publish`，其中资源包括以下 MQTT 主题的 ARN：
    + `$aws/things/coreDeviceThingName*-gci/shadow/get`
  + `iot:Subscribe`，其中资源包括以 ARNs 下 MQTT 主题过滤器：
    + `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
    + `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`
  + `iot:Receive`，其中资源包括以 ARNs 下 MQTT 主题：
    + `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
    + `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`

  有关更多信息，请参阅[AWS IoT 数据平面操作策略](device-auth.md#iot-policies)和[支持客户端设备的最低 AWS IoT 政策](device-auth.md#client-device-support-minimal-iot-policy)。
+ （可选）要使用离线身份验证， AWS IoT Greengrass 服务使用的 AWS Identity and Access Management (IAM) 角色必须包含以下权限：
  + `greengrass:ListClientDevicesAssociatedWithCoreDevice`，支持核心设备列出客户端以进行离线身份验证。
+ 支持在 VPC 中运行客户端设备身份验证组件。要在 VPC 中部署此组件，需要满足以下条件。
  + 客户端设备身份验证组件必须连接到 AWS IoT data、 AWS IoT 凭证和 Amazon S3。

### 端点和端口
<a name="client-device-auth-component-endpoints"></a>

除基本操作所需的端点和端口外，此组件还必须能够对以下端点和端口执行出站请求。有关更多信息，请参阅 [允许设备流量通过代理或防火墙](allow-device-traffic.md)。


| 终端节点 | 端口 | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `iot.region.amazonaws.com`  | 443 | 是 |  用于获取有关 AWS IoT 事物证书的信息。  | 

## 依赖项
<a name="client-device-auth-component-dependencies"></a>

部署组件时， AWS IoT Greengrass 还会部署其依赖项的兼容版本。这意味着您必须满足组件及其所有依赖关系的要求，才能成功部署组件。本部分列出了此组件的[已发布版本](#client-device-auth-component-changelog)的依赖关系，以及定义每个依赖关系的组件版本的语义版本约束。您还可以在 [AWS IoT Greengrass 控制台](https://console.aws.amazon.com//greengrass)中查看每个组件版本的依赖关系。在组件详细信息页面上，查找**依赖关系**列表。

------
#### [ 2.5.5 ]

下表列出了此组件版本 2.5.5 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.17.0 | 软性 | 

------
#### [ 2.5.4 ]

下表列出了此组件版本 2.5.4 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.16.0 | 软性 | 

------
#### [ 2.5.2 – 2.5.3 ]

下表列出了此组件版本 2.5.2 和 2.5.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.15.0 | 软性 | 

------
#### [ 2.5.1 ]

下表列出了此组件版本 2.5.1 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.14.0 | 软性 | 

------
#### [ 2.4.4 - 2.5.0 ]

下表列出了此组件版本 2.4.4 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.13.0 | 软性 | 

------
#### [ 2.4.3 ]

下表列出了此组件版本 2.4.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.12.0 | 软性 | 

------
#### [ 2.4.1 and 2.4.2 ]

下表列出了此组件版本 2.4.1 和 2.4.2 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.11.0 | 软性 | 

------
#### [ 2.3.0 – 2.4.0 ]

下表列出了此组件版本 2.3.0 到 2.4.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | 软性 | 

------
#### [ 2.3.0 ]

下表列出了此组件版本 2.3.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | 软性 | 

------
#### [ 2.2.3 ]

下表列出了此组件版本 2.2.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <=2.9.0 | 软性 | 

------
#### [ 2.2.2 ]

下表列出了此组件版本 2.2.2 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <=2.8.0 | 软性 | 

------
#### [ 2.2.1 ]

下表列出了此组件版本 2.2.1 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.8.0 | 软性 | 

------
#### [ 2.2.0 ]

下表列出了此组件版本 2.2.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.7.0 | 软性 | 

------
#### [ 2.1.0 ]

下表列出了此组件版本 2.1.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.7.0 | 软性 | 

------
#### [ 2.0.4 ]

下表列出了此组件的版本 2.0.4 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.6.0 | 软性 | 

------
#### [ 2.0.2 and 2.0.3 ]

下表列出了此组件版本 2.0.2 和 2.0.3 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.5.0 | 软性 | 

------
#### [ 2.0.1 ]

下表列出了此组件的版本 2.0.1 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.4.0 | 软性 | 

------
#### [ 2.0.0 ]

下表列出了此组件版本 2.0.0 的依赖关系。


| 依赖关系 | 兼容版本 | 依赖关系类型 | 
| --- | --- | --- | 
| [Greengrass Nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.3.0 | 软性 | 

------

有关组件依赖关系的更多信息，请参阅[组件配方参考](component-recipe-reference.md#recipe-reference-component-dependencies)。

## 配置
<a name="client-device-auth-component-configuration"></a>

此组件提供您可以在部署组件时自定义的以下配置参数。

**注意**  
订阅权限在客户端向本地 MQTT 代理发出订阅请求期间进行评估。如果客户端的现有订阅权限被撤销，则客户端将无法再订阅主题。但是，它将继续接收来自以前订阅的任何主题的消息。为防止这种行为，应在撤销订阅权限后重新启动本地 MQTT 代理，以强制客户端重新授权。  
对于 MQTT 5 代理（EMQX）组件，请更新 `restartIdentifier` 配置以重新启动 MQTT 5 代理。  
对于 MQTT 3.1.1 代理（Moquette）组件，默认情况下，当服务器证书更改以强制客户端重新授权时，它会每周重新启动一次。要强制重新启动，您可以更改核心设备的连接信息（IP 地址），也可以进行部署以移除代理组件，稍后再部署。

------
#### [ v2.5.0 – 2.5.4 ]

`deviceGroups`  
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称的开头和结尾使用此通配符，以匹配名称以您指定的字符串开头或结尾的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName`— 客户端设备的 AWS IoT 名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 结尾的客户端设备。  

```
thingName: *MyClientDevice
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + `mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源不支持 MQTT 主题通配符。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以在资源变量中的任意位置指定 `*` 通配符，以允许访问所有资源。例如，您可以指定 **mqtt:topic:my\$1** 以允许访问与该输入相匹配的资源。  
支持以下资源变量。  
+ `mqtt:topic:${iot:Connection.Thing.ThingName}`

  这将解析为正在评估策略的 AWS IoT Core 注册表中事物的名称。 AWS IoT Core 使用设备在进行身份验证时出示的证书来确定使用哪个东西来验证连接。只有当设备通过协议通过 MQTT 或 MQTT 进行连接时，此策略变量才可用。 WebSocket   
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

`certificateAuthority`  
（可选）证书颁发机构配置选项，使用您自己的中间证书颁发机构替换核心设备中间颁发机构。  
如果您将 Greengrass 核心设备配置为自定义证书颁发机构（CA），并使用相同的 CA 颁发客户端设备证书，则 Greengrass 会绕过对客户端设备 MQTT 操作的授权策略检查。客户端设备身份验证组件完全信任使用由配置 CA 签署的证书的客户端。  
要在使用自定义 CA 时限制此行为，请使用其他 CA 或中间 CA 创建和签署客户端设备，然后调整 `certificateUri` 和 `certificateChainUri` 字段以指向正确的中间 CA。
 该对象包含以下信息。    
certificateUri  
证书的位置。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书的 URI。  
`certificateChainUri`  
核心设备 CA 的设备链的 ARN。这应该是返回到您的根 CA 的完整证书链。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书链的 URI。  
`privateKeyUri`  
核心设备私钥的位置。这可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书私钥的 URI。

`security`  
（可选）此核心设备的安全配置选项。该对象包含以下信息。    
`clientDeviceTrustDurationMinutes`  
在要求客户端设备重新进行身份验证之前，客户端设备的身份验证信息可以被信任的持续时间（以分钟为单位）。默认值是 1。

`metrics`  
（可选）此核心设备的指标选项。仅当客户端设备身份验证出现错误时，才会显示错误指标。该对象包含以下信息：    
`disableMetrics`  
如果 `disableMetrics` 字段设置为 `true`，则客户端设备身份验证将不会收集指标。  
默认值：`false`  
`aggregatePeriodSeconds`  
以秒为单位的聚合周期，决定了客户端设备身份验证聚合指标并将其发送给遥测座席的频率。这不会改变指标的发布频率，因为遥测座席仍然每天发布一次。  
默认值：`3600`

startupTimeoutSeconds  
（可选）组件启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 `ERRORED`。  
默认值：`120`

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

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

**Example 示例：配置合并更新（使用事物名称策略）**  <a name="client-device-auth-component-configuration-example-mythingname"></a>
以下示例配置支持客户端设备在以客户端设备的事物名称开头并以字符串 `topic` 结尾的主题上发布。  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "myThing": {
        "selectionRule": "thingName: *",
        "policyName": "MyThingNamePolicy"
      }
    },
    "policies": {
      "MyThingNamePolicy": {
        "policyStatement": {
          "statementDescription": "mqtt publish",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:${iot:Connection.Thing.ThingName}/*/topic"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.4.5 ]

`deviceGroups`  
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称的开头和结尾使用此通配符，以匹配名称以您指定的字符串开头或结尾的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName`— 客户端设备的 AWS IoT 名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 结尾的客户端设备。  

```
thingName: *MyClientDevice
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

`certificateAuthority`  
（可选）证书颁发机构配置选项，使用您自己的中间证书颁发机构替换核心设备中间颁发机构。  
如果您将 Greengrass 核心设备配置为自定义证书颁发机构（CA），并使用相同的 CA 颁发客户端设备证书，则 Greengrass 会绕过对客户端设备 MQTT 操作的授权策略检查。客户端设备身份验证组件完全信任使用由配置 CA 签署的证书的客户端。  
要在使用自定义 CA 时限制此行为，请使用其他 CA 或中间 CA 创建和签署客户端设备，然后调整 `certificateUri` 和 `certificateChainUri` 字段以指向正确的中间 CA。
 该对象包含以下信息。    
certificateUri  
证书的位置。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书的 URI。  
`certificateChainUri`  
核心设备 CA 的设备链的 ARN。这应该是返回到您的根 CA 的完整证书链。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书链的 URI。  
`privateKeyUri`  
核心设备私钥的位置。这可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书私钥的 URI。

`security`  
（可选）此核心设备的安全配置选项。该对象包含以下信息。    
`clientDeviceTrustDurationMinutes`  
在要求客户端设备重新进行身份验证之前，客户端设备的身份验证信息可以被信任的持续时间（以分钟为单位）。默认值是 1。

`metrics`  
（可选）此核心设备的指标选项。仅当客户端设备身份验证出现错误时，才会显示错误指标。该对象包含以下信息：    
`disableMetrics`  
如果 `disableMetrics` 字段设置为 `true`，则客户端设备身份验证将不会收集指标。  
默认值：`false`  
`aggregatePeriodSeconds`  
以秒为单位的聚合周期，决定了客户端设备身份验证聚合指标并将其发送给遥测座席的频率。这不会改变指标的发布频率，因为遥测座席仍然每天发布一次。  
默认值：`3600`

startupTimeoutSeconds  
（可选）组件启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 `ERRORED`。  
默认值：`120`

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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.2 - v2.4.4 ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

`certificateAuthority`  
（可选）证书颁发机构配置选项，使用您自己的中间证书颁发机构替换核心设备中间颁发机构。  
如果您将 Greengrass 核心设备配置为自定义证书颁发机构（CA），并使用相同的 CA 颁发客户端设备证书，则 Greengrass 会绕过对客户端设备 MQTT 操作的授权策略检查。客户端设备身份验证组件完全信任使用由配置 CA 签署的证书的客户端。  
要在使用自定义 CA 时限制此行为，请使用其他 CA 或中间 CA 创建和签署客户端设备，然后调整 `certificateUri` 和 `certificateChainUri` 字段以指向正确的中间 CA。
 该对象包含以下信息。    
certificateUri  
证书的位置。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书的 URI。  
`certificateChainUri`  
核心设备 CA 的设备链的 ARN。这应该是返回到您的根 CA 的完整证书链。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书链的 URI。  
`privateKeyUri`  
核心设备私钥的位置。这可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书私钥的 URI。

`security`  
（可选）此核心设备的安全配置选项。该对象包含以下信息。    
`clientDeviceTrustDurationMinutes`  
在要求客户端设备重新进行身份验证之前，客户端设备的身份验证信息可以被信任的持续时间（以分钟为单位）。默认值是 1。

`metrics`  
（可选）此核心设备的指标选项。仅当客户端设备身份验证出现错误时，才会显示错误指标。该对象包含以下信息：    
`disableMetrics`  
如果 `disableMetrics` 字段设置为 `true`，则客户端设备身份验证将不会收集指标。  
默认值：`false`  
`aggregatePeriodSeconds`  
以秒为单位的聚合周期，决定了客户端设备身份验证聚合指标并将其发送给遥测座席的频率。这不会改变指标的发布频率，因为遥测座席仍然每天发布一次。  
默认值：`3600`

startupTimeoutSeconds  
（可选）组件启动的最长时间（以秒为单位）。如果时间超过此超时时间，则组件的状态将更改为 `ERRORED`。  
默认值：`120`

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

`certificateAuthority`  
（可选）证书颁发机构配置选项，使用您自己的中间证书颁发机构替换核心设备中间颁发机构。该对象包含以下信息。  
 该对象包含以下信息：    
certificateUri  
证书的位置。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书的 URI。  
`certificateChainUri`  
核心设备 CA 的设备链的 ARN。这应该是返回到您的根 CA 的完整证书链。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书链的 URI。  
`privateKeyUri`  
核心设备私钥的位置。这可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书私钥的 URI。

`security`  
（可选）此核心设备的安全配置选项。该对象包含以下信息。    
`clientDeviceTrustDurationMinutes`  
在要求客户端设备重新进行身份验证之前，客户端设备的身份验证信息可以被信任的持续时间（以分钟为单位）。默认值是 1。

`metrics`  
（可选）此核心设备的指标选项。仅当客户端设备身份验证出现错误时，才会显示错误指标。该对象包含以下信息：    
`disableMetrics`  
如果 `disableMetrics` 字段设置为 `true`，则客户端设备身份验证将不会收集指标。  
默认值：`false`  
`aggregatePeriodSeconds`  
以秒为单位的聚合周期，决定了客户端设备身份验证聚合指标并将其发送给遥测座席的频率。这不会改变指标的发布频率，因为遥测座席仍然每天发布一次。  
默认值：`3600`

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

`certificateAuthority`  
（可选）证书颁发机构配置选项，使用您自己的中间证书颁发机构替换核心设备中间颁发机构。该对象包含以下信息。    
certificateUri  
证书的位置。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书的 URI。  
`certificateChainUri`  
核心设备 CA 的设备链的 ARN。这应该是返回到您的根 CA 的完整证书链。它可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书链的 URI。  
`privateKeyUri`  
核心设备私钥的位置。这可以是文件系统 URI，也可以是指向硬件安全模块中存储的证书私钥的 URI。

`security`  
（可选）此核心设备的安全配置选项。该对象包含以下信息。    
`clientDeviceTrustDurationMinutes`  
在要求客户端设备重新进行身份验证之前，客户端设备的身份验证信息可以被信任的持续时间（以分钟为单位）。默认值是 1。

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

`performance`  
（可选）此核心设备的性能配置选项。该对象包含以下信息：    
`maxActiveAuthTokens`  
（可选）活动客户端设备授权令牌的最大数量。您可以增加此数字，以支持更多的客户端设备能够连接到单个核心设备，而无需重新对其进行身份验证。  
默认值：`2500`  
`cloudRequestQueueSize`  
（可选）在此组件拒绝 AWS 云 请求之前要排队的最大请求数。  
默认值：`100`  
`maxConcurrentCloudRequests`  
（可选）要向 AWS 云发送的并发请求的最大数量。您可以增加此数字，以提高您用于连接大量客户端设备的核心设备的身份验证性能。  
默认值：`1`

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
（可选）此核心设备的证书配置选项。该对象包含以下信息：    
`serverCertificateValiditySeconds`  
（可选）本地 MQTT 服务器证书到期后的时间长度（以秒为单位）。您可以配置此选项，以自定义客户端设备断开连接并重新连接到核心设备的频率。  
此组件在本地 MQTT 服务器证书到期前 24 小时对其进行轮换。MQTT 代理（例如 [Moquette MQTT 代理组件](mqtt-broker-moquette-component.md)）生成新证书并重新启动。发生这种情况时，连接到该核心设备的所有客户端设备都将断开连接。客户端设备可以在短时间后重新连接到核心设备。  
默认值：`604800`（7 天）  
最小值：`172800`（2 天）  
最大值：`864000`（10 天）

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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`  <a name="client-device-auth-component-configuration-devicegroups"></a>
设备组是指有权与核心设备连接和通信的客户端设备组。使用选择规则来识别客户端设备组，并定义*客户端设备授权策略*，为每个设备组指定权限。  
该对象包含以下信息：    
`formatVersion`  
此配置对象的格式版本。  
从以下选项中进行选择：  
+ `2021-03-05`  
`definitions`  
此核心设备的设备组。每个定义都指定了用于评估客户端设备是否为组成员的*选择规则*。每个定义还指定了要应用于与选择规则相匹配的客户端设备的权限策略。如果某客户端设备是多个设备组的成员，则该设备的权限由每个组的权限策略组成。  
该对象包含以下信息：    
`groupNameKey`  
该设备组的名称。*groupNameKey*替换为可帮助您识别此设备组的名称。  
该对象包含以下信息：    
`selectionRule`  
用于指定哪些客户端设备是该设备组成员的查询。当客户端设备连接时，核心设备会评估此选择规则，以确定该客户端设备是否为该设备组的成员。如果客户端设备是成员，则核心设备使用该设备组的策略来授权客户端设备的操作。  
每条选择规则至少包含一个*选择规则子句*，即可以匹配客户端设备的单个表达式查询。选择规则使用的查询语法与 AWS IoT 舰队索引相同。有关选择规则语法的更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [AWS IoT 实例集索引查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。  
使用 `*` 通配符，将多个客户端设备与一个选择规则子句进行匹配。您可以在事物名称结尾使用此通配符，以匹配名称以您指定的字符串开头的客户端设备。您还可以使用此通配符来匹配所有客户端设备。  
要选择包含冒号字符（`:`）的值，请使用反斜杠字符（`\\`）对冒号进行转义。在 JSON 等格式中，您必须对反斜杠字符进行转义，因此您在冒号字符之前输入两个反斜杠字符。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 以选择名称为 `MyTeam:ClientDevice1` 的事物。
您可指定以下选择器：  
+ `thingName` – 客户端设备的 AWS IoT 事物的名称。

**Example 选择规则示例**  
以下选择规则匹配名称为 `MyClientDevice1` 或 `MyClientDevice2` 的客户端设备。  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example 选择规则示例（使用通配符）**  
以下选择规则匹配名称以 `MyClientDevice` 开头的客户端设备。  

```
thingName: MyClientDevice*
```

**Example 选择规则示例（匹配所有设备）**  
以下选择规则匹配所有客户端设备。  

```
thingName: *
```  
`policyName`  
适用于该设备组中的客户端设备的权限策略。指定您在 `policies` 对象中定义的策略的名称。  
`policies`  
针对连接到核心设备的客户端设备的客户端设备授权策略。每个授权策略都指定了一组操作以及客户端设备可以用来执行这些操作的资源。  
该对象包含以下信息：    
`policyNameKey`  
该授权策略的名称。*policyNameKey*替换为可帮助您识别此授权策略的名称。您可以使用此策略名称来定义哪个策略适用于设备组。  
该对象包含以下信息：    
`statementNameKey`  
该策略语句的名称。*statementNameKey*替换为可帮助您识别此政策声明的名称。  
该对象包含以下信息：    
`operations`  
允许使用此策略中的资源的操作列表。  
您可以包括以下任一操作：  
+ `mqtt:connect` – 授予权限以连接核心设备。客户端设备必须具有此权限才能连接到核心设备。

  此操作支持以下资源：
  + `mqtt:clientId:deviceClientId` – 根据客户端设备用于连接核心设备的 MQTT 代理的客户端 ID 来限制访问。*deviceClientId*替换为要使用的客户端 ID。
+ `mqtt:publish` – 授予权限以向主题发布 MQTT 消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – 根据客户端设备用于发布消息的 MQTT 主题来限制访问。*mqttTopic*替换为要使用的主题。

    此资源不支持 MQTT 主题通配符。
+ `mqtt:subscribe` – 授予权限以订阅 MQTT 主题筛选条件，以接收消息。

  此操作支持以下资源：
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – 根据客户端设备可用于订阅消息的 MQTT 主题来限制访问。*mqttTopicFilter*替换为要使用的主题筛选器。

    此资源支持 `+` 和 `#` MQTT 主题通配符。有关更多信息，请参阅《AWS IoT Core 开发人员指南》**中的 [MMQTT 主题](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

    客户端设备可以订阅您允许的确切主题筛选条件。例如，如果您允许客户端设备订阅 `mqtt:topicfilter:client/+/status` 资源，则客户端设备可以订阅 `client/+/status`，但不能订阅 `client/client1/status`。
您可以指定 `*` 通配符以允许访问所有操作。  
`resources`  
允许此策略中的操作的资源列表。指定与此策略中的操作相对应的资源。例如，您可以在指定 `mqtt:publish` 操作的策略中指定 MQTT 主题资源列表（`mqtt:topic:mqttTopic`）。  
您可以指定 `*` 通配符以允许访问所有资源。您不能使用 `*` 通配符来匹配部分资源标识符。例如，您可以指定 **"resources": "\$1"**，但不能指定 **"resources": "mqtt:clientId:\$1"**。  
`statementDescription`  
（可选）此政策语句的描述。

**Example 示例：配置合并更新（使用限制策略）**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
以下示例配置指定允许名称以开头的`MyClientDevice`客户端设备 publish/subscribe 在所有主题上进行连接。  

```
{
  "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 示例：配置合并更新（使用宽松策略）**  <a name="client-device-auth-component-configuration-example-permissive"></a>
以下示例配置指定允许所有客户端设备 publish/subscribe 在所有主题上进行连接。  

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

------

## 本地日志文件
<a name="client-device-auth-component-log-file"></a>

此组件使用与 [Greengrass Nucleus](greengrass-nucleus-component.md) 组件相同的日志文件。

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**查看此组件的日志**
+ 在核心设备上运行以下命令可实时查看此组件的日志文件。将`/greengrass/v2`或*C:\$1greengrass\$1v2*替换为 AWS IoT Greengrass 根文件夹的路径。

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## 更改日志
<a name="client-device-auth-component-changelog"></a>

下表介绍每个组件版本的更改。


|  **版本**  |  **更改**  | 
| --- | --- | 
|  2.5.5  |  Greengrass nucleus 版本 2.16.0 版本的版本已更新。  | 
|  2.5.4  | Greengrass nucleus 版本 2.15.0 版本的版本已更新。 | 
|  2.5.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.5.2  |  Greengrass nucleus 版本 2.14.0 版本的版本已更新。  | 
|  2.5.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.5.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.4.5  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html) | 
|  2.4.4  | 版本更新为 Greengrass Nucleus 版本 2.12.0 发布版。 | 
|  2.4.3  | 版本更新为 Greengrass Nucleus 版本 2.11.0 发布版。 | 
|  2.4.2  |  <a name="changelog-client-device-auth-2.4.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.4.1  | 版本更新为 Greengrass Nucleus 版本 2.10.0 发布版。 | 
|  2.4.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.0  |   此版本不再可用。此版本的改进将在此组件的更高版本中提供。  新特征 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.2.3  | 版本更新为 Greengrass Nucleus 版本 2.8.0 发布版。 | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.2.1  |  版本更新为 Greengrass Nucleus 版本 2.7.0 发布版。 | 
|  2.2.0  |  <a name="changelog-client-device-auth-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.0.4  |  版本更新为 Greengrass Nucleus 版本 2.5.0 发布版。  | 
|  2.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.0.2  |  版本更新为 Greengrass Nucleus 版本 2.4.0 发布版。  | 
|  2.0.1  |  版本更新为 Greengrass Nucleus 版本 2.3.0 发布版。  | 
|  2.0.0  |  初始版本。  |