本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 通过 CSV 文件将用户导入用户池中
如果您有外部身份存储，并且有时间为新的本地用户准备用户池，那么在迁移到 Amazon Cognito 用户池，选择从逗号分隔值（CSV）文件批量导入用户既省时省力，又可降低成本。CSV 文件导入是先下载和填入模板文件，然后在导入任务中将该文件移交给用户池的过程。您可以使用 CSV 导入来快速创建测试用户。您还可以通过编程的方式，使用读取 API 请求从外部身份存储中获取数据，然后解析这些数据的详细信息和属性，再将它们写入到文件中。
默认情况下，导入过程会为除**密码**之外的所有用户属性设置值。这意味着，用户必须在首次登录时更改密码。使用此方法导入用户时，用户处于 `RESET_REQUIRED` 状态。
或者，您可以导入具有现有密码哈希值的用户。当您在创建导入任务时指定密码哈希算法并在您的 CSV 文件中包含密码哈希时，Amazon Cognito 会使用用户的现有密码导入用户。这些用户是按`CONFIRMED`状态创建的，无需重置密码即可立即登录。有关更多信息，请参阅 [使用密码哈希导入用户](#cognito-user-pools-import-password-hash)。
从 CSV 导入用户最省力的方法是在用户池中激活[无密码登录](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)。借助电子邮件地址和电话号码属性以及正确的用户池配置，用户可以在导入作业完成后立即使用电子邮件或短信一次性密码（OTP）登录。有关更多信息，请参阅 [要求导入的用户重置密码](#cognito-user-pools-using-import-tool-password-reset)。
您也可以使用 [AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API 请求，将 `Permanent` 参数设置为 `true` 来设置用户的密码。CSV 导入不会计入用户池中的计费月活跃用户（MAU）。但密码重置操作会生成 MAU。要在导入大量可能不会立即处于活动状态的带密码用户时控制成本，请将您的应用程序设置为在用户登录并收到 `RESET_REQUIRED` 质询时提示他们输入新密码。
**注意**
每个用户的创建日期就是将该用户导入用户池中的日期。创建日期不是导入的属性之一。
**创建用户导入任务的步骤**
1. 在 AWS Identity and Access Management (IAM) 控制台中创建 Amazon L CloudWatch ogs 角色。
1. 创建用户导入 .csv 文件。
1. 创建并运行用户导入任务。（可选）指定密码哈希算法，以导入具有现有密码哈希值的用户。
1. 上传用户导入 .csv 文件。
1. 启动并运行用户导入任务。
1. CloudWatch 用于查看事件日志。
1. 如果您没有导入密码哈希，请要求导入的用户重置密码。
**更多资源**
+ [Cognito 用户配置文件导出参考架构](https://aws.amazon.com/solutions/implementations/cognito-user-profiles-export-reference-architecture/)，用于在用户池之间导出用户账户
**Topics**
+ [创建日 CloudWatch 志 IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role)
+ [创建用户导入 CSV 文件](#cognito-user-pools-using-import-tool-csv-header)
+ [创建并运行 Amazon Cognito 用户池导入任务](#cognito-user-pools-creating-import-job)
+ [在 CloudWatch 控制台中查看用户池导入结果](#cognito-user-pools-using-import-tool-cloudwatch)
+ [要求导入的用户重置密码](#cognito-user-pools-using-import-tool-password-reset)
+ [使用密码哈希导入用户](#cognito-user-pools-import-password-hash)
## 创建日 CloudWatch 志 IAM 角色
如果您使用的是 Amazon Cognito CLI 或 API，则需要创建一个 CloudWatch IAM 角色。以下过程介绍如何创建一个 IAM 角色，Amazon Cognito 可以使用该角色将导入任务的结果写入日志。 CloudWatch
**注意**
在 Amazon Cognito 控制台中创建导入作业时，您可以同时创建 IAM 角色。当您选择 **Create a new IAM role**（创建新 IAM 角色）时，Amazon Cognito 会自动对该角色应用相应的信任策略和 IAM policy。
**为用户池导入创建 CloudWatch 日志 IAM 角色 (AWS CLI，API）**
1. 登录 AWS 管理控制台 并打开 IAM 控制台，网址为[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 为创建新的 IAM 角色 AWS 服务。有关详细说明，请参阅《AWS Identity and Access Management 用户指南》**中的[为 AWS 服务创建一个角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)。
1. 当您为 **Trusted entity type**（可信实体类型）选择 **Use case**（使用案例）时，请选择任意服务。Amazon Cognito 目前未在服务使用案例中列出。
1. 在 **Add permissions**（添加权限）屏幕中，选择 **Create policy**（创建策略）并插入以下策略声明。例如，{{REGION}} AWS 区域 替换为用户池中的`us-east-1`。例如{{ACCOUNT}}，用您的 AWS 账户 身份证替换`111122223333`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:{{us-east-1}}:{{111122223333}}:log-group:/aws/cognito/*"
]
}
]
}
```
------
1. 由于您在创建角色时没有选择 Amazon Cognito 作为可信实体，因此您现在必须手动编辑该角色的信任关系。在 IAM 控制台的导航窗格中选择 **Roles**（角色），然后选择您创建的新角色。
1. 选择 **Trust relationships（信任关系）**选项卡。
1. 选择**编辑信任策略**。
1. 将以下策略声明粘贴到 **Edit trust policy**（编辑信任策略）中，替换任何现有文本：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cognito-idp.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 选择**更新策略**。
1. 记下 角色 ARN。您在创建导入作业时需要此 ARN。
## 创建用户导入 CSV 文件
您必须先创建逗号分隔值（CSV，Comma-Separated Value）文件，在其中包含要导入的用户及其属性，然后才能将现有用户导入用户池中。从用户池中，您可以检索其标头反映了您的用户池的属性架构的用户导入文件。然后，您可以插入符合 [设置 CSV 文件的格式](#cognito-user-pools-using-import-tool-formatting-csv-file) 中的格式要求的用户信息。
### 下载 CSV 文件标头（控制台）
使用以下步骤下载 CSV 标头文件。
**下载 CSV 文件标头**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。系统可能会提示您输入 AWS 凭证。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单。
1. 在 **Import users**（导入用户）部分中，选择 **Create an import job**（创建导入作业）。
1. 在 **Upload CSV**（上传 CSV）下，选择 *template.csv* 链接并下载 CSV 文件。
### 正在下载 CSV 文件标头 (AWS CLI)
要获取正确的标题列表，请从**用户**菜单中的**导入用户**下选择**创建导入作业**。在随后的对话框中，选择 `template.csv` 链接以下载包含您的用户池属性的模板文件。
您也可以运行以下 CLI 命令，其中{{USER\_POOL\_ID}}是要将用户导入到的用户池的用户池标识符：
```
aws cognito-idp get-csv-header --user-pool-id "{{USER_POOL_ID}}"
```
示例响应：
```
{
"CSVHeader": [
"name",
"given_name",
"family_name",
"middle_name",
"nickname",
"preferred_username",
"profile",
"picture",
"website",
"email",
"email_verified",
"gender",
"birthdate",
"zoneinfo",
"locale",
"phone_number",
"phone_number_verified",
"address",
"updated_at",
"cognito:mfa_enabled",
"cognito:username"
],
"UserPoolId": "{{USER_POOL_ID}}"
}
```
### 设置 CSV 文件的格式
下载的用户导入 CSV 标头文件类似于以下字符串。它还包括您已添加到用户池的所有自定义属性。
```
cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
```
编辑 CSV 文件，以使文件包含此标头和用户的属性值，并根据以下规则设置格式：
**注意**
有关属性值（如电话号码的正确格式）的更多信息，请参阅[使用用户属性](user-pool-settings-attributes.md)。
+ 文件的第一行是已下载的包含用户属性名称的标头行。
+ CSV 文件中列的顺序不重要。
+ 第一行之后的每一行都包含用户的属性值。
+ 标头中的所有列都必须存在，但您不需要在每一列中提供值。
+ 以下属性为必需属性：
+ **cognito:username**
+ **email\_verified** 或 **phone\_number\_verified**
+ 每个用户至少有一个自动验证属性必须为 `true`。自动验证的属性是新用户加入您的用户池时，Amazon Cognito 自动向其发送验证码的电子邮件地址或电话号码。
+ 用户池必须至少有一个自动验证属性，要么是 **email\_verified**，要么是 **phone\_number\_verified**。如果用户池没有自动验证属性，则导入任务不会启动。
+ 如果用户池只有一个自动验证属性，则该属性必须针对每个用户进行验证。例如，如果用户池只有 **phone\_number** 为自动验证属性，则每个用户的 **phone\_number\_verified** 值都必须为 `true`。
**注意**
对于重置其密码的用户，用户必须拥有经过验证的电子邮件或电话号码。Amazon Cognito 将包含重置密码代码的消息发送到 CSV 文件中指定的电子邮件或电话号码。如果将消息发送到电话号码，则通过 SMS 消息发送。有关更多信息，请参阅 [在注册时验证联系人信息](signing-up-users-in-your-app.md#allowing-users-to-sign-up-and-confirm-themselves)。
+ **email**（如果 **email\_verified** 为 `true`）
+ **phone\_number**（如果 **phone\_number\_verified** 为 `true`）
+ 创建用户池时标记为必需的所有属性
+ 字符串式的属性值*不* 应该用引号括起来。
+ 如果属性值包含逗号，则您必须在逗号前使用反斜杠 (\\)。这是因为 CSV 文件中的字段使用逗号分隔。
+ CSV 文件内容的 UTF-8 格式应不带字节顺序标记。
+ **cognito:username** 字段是必填项，并且在用户池中必须是唯一的。它可以是任何 Unicode 字符串。但是，它不能包含空格或制表符。
+ **出生日期**值（如果存在）必须采用以下格式*{{mm/dd/yyyy}}*。也就是说，如果生日日期为 1985 年 2 月 1 日，则必须编码为 **02/01/1985**。
+ **cognito:mfa\_enabled** 字段必须符合用户池的 MFA 要求。如果您已将用户池设置为需要进行多重身份验证（MFA），则所有用户的此字段都必须为 `true` 或为空。如果您已将 MFA 设置为关闭，则所有用户的此字段都必须为 `false` 或为空。空值将导入用户的 MFA-enabled 状态设置为用户池所需的状态。无论您是否设置了值，您都可以在没有有效 MFA 因子的 MFA-required 用户池中导入用户。`cognito:mfa_enabled`处于此状态的用户已激活 MFA，但在配置电子邮件属性、电话号码属性或 TOTP 之前无法登录，并且该配置是用户池中的有效 MFA 因素。
+ 最大长度为 16000 个字符。
+ CSV 文件的最大大小为 100MB。
+ 文件中的最大行（用户）数为 5,00000。此最大值不包括标题行。
+ **updated\_at** 字段值应为纪元时间（用秒表示），例如：**1471453471**。
+ 属性值中的所有前导空格或尾部空格均应去除。
以下列表是没有自定义属性的用户池的 CSV 导入文件示例。您的用户池架构可能与此示例有所不同。在这种情况下，您必须在从用户池下载的 CSV 模板中提供测试值。
```
cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
John,,John,Doe,,,,,,,johndoe@example.com,TRUE,,02/01/1985,,,+12345550100,TRUE,123 Any Street,,FALSE
Jane,,Jane,Roe,,,,,,,janeroe@example.com,TRUE,,01/01/1985,,,+12345550199,TRUE,100 Main Street,,FALSE
```
## 创建并运行 Amazon Cognito 用户池导入任务
本节介绍如何使用 Amazon Cognito 控制台和 AWS Command Line Interface ()AWS CLI创建和运行用户池导入任务。
**Topics**
+ [从 CSV 文件导入用户（控制台）](#cognito-user-pools-using-import-tool-console)
+ [导入用户 (AWS CLI)](#cognito-user-pools-using-import-tool-cli)
### 从 CSV 文件导入用户（控制台）
以下过程介绍了如何从 CSV 文件导入用户。
**从 CSV 文件导入用户（控制台）**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。系统可能会提示您输入 AWS 凭证。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单。
1. 在 **Import users**（导入用户）部分中，选择 **Create an import job**（创建导入作业）。
1. 在 **Create import job**（创建导入作业）页面上，输入 **Job name**（作业名称）。
1. 选择 **Create a new IAM role**（创建新的 IAM 角色）或者 **Use an existing IAM role**（使用现有 IAM 角色）。
1. 如果您选择 **Create a new IAM role**（创建新的 IAM 角色），请输入新角色的名称。Amazon Cognito 将自动创建具有正确权限和信任关系的角色。创建导入作业的 IAM 主体必须具有创建 IAM 角色的权限。
1. 如果您选择 **Use an existing IAM role**（使用现有 IAM 角色），请从 **IAM role selection**（IAM 角色选择）下的列表中选择一个角色。此角色必须具有 [创建日 CloudWatch 志 IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role) 中所述的权限和信任策略。
1. 在**上传 CSV** 下，选择**选择文件**并附加准备好的 CSV 文件。
1. 选择 **Create job**（创建作业）可提交作业，但稍后再启动。选择 **Create and start job**（创建并启动作业）可提交您的作业并立即启动。
1. 如果您创建了作业但未启动作业，则可以稍后再启动。在**用户**菜单的**导入用户**下，选择导入作业，然后选择**开始**。您也可以从 AWS SDK 提交 [StartUserImportJob](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_StartUserImportJob.html)API 请求。
1. 在**用户**菜单的**导入用户**下，监控用户导入作业的进度。如果您的作业不成功，则可以选择 **Status**（状态）值。要了解更多详细信息，请选择**查看 CloudWatch 日志以了解更多详细信息**，然后在 CloudWatch 日志控制台中查看所有问题。
### 导入用户 (AWS CLI)
以下 CLI 命令可用于将用户导入到用户池：
+ `create-user-import-job`
+ `get-csv-header`
+ `describe-user-import-job`
+ `list-user-import-jobs`
+ `start-user-import-job`
+ `stop-user-import-job`
要获取这些命令的命令行选项列表，请使用 `help` 命令行选项。例如：
```
aws cognito-idp get-csv-header help
```
#### 创建用户导入任务
创建 CSV 文件后，通过运行以下 CLI 命令创建用户导入任务，其中{{JOB\_NAME}}是您为任务选择的名称，{{USER\_POOL\_ID}}是要向其中添加新用户的用户池的用户池 ID，{{ROLE\_ARN}}也是您在中收到的角色 ARN：[创建日 CloudWatch 志 IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role)
```
aws cognito-idp create-user-import-job --job-name "{{JOB_NAME}}" --user-pool-id "{{USER_POOL_ID}}" --cloud-watch-logs-role-arn "{{ROLE_ARN}}"
```
响应中{{PRE\_SIGNED\_URL}}返回的有效期为 15 分钟。在此之后，它将过期，而您必须创建新的用户导入任务以获取新的 URL。
**Example 响应：**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl": "{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn": "{{ROLE_ARN}}",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
#### 用户导入任务的状态值
在对用户导入命令的响应中，您将看到以下 `Status` 值当中的其中一个值：
+ `Created` – 任务已创建但未启动。
+ `Pending` – 转换状态。您已启动任务，但它尚未开始导入用户。
+ `InProgress` – 任务已启动，正在导入用户。
+ `Stopping` – 您已停止任务，但任务尚未停止导入用户。
+ `Stopped` – 您已停止任务，且任务已停止导入用户。
+ `Succeeded` – 任务已成功完成。
+ `Failed` – 任务因错误而停止。
+ `Expired` – 您创建了一个任务，但未在 24-48 小时内启动任务。与任务关联的所有数据已删除，且任务无法启动。
#### 上传 CSV 文件
使用以下 `curl` 命令将包含用户数据的 CSV 文件上传到您从 `create-user-import-job` 命令的响应中获取的预签名 URL。
```
curl -v -T "{{PATH_TO_CSV_FILE}}" -H "x-amz-server-side-encryption:aws:kms" "{{PRE_SIGNED_URL}}"
```
在此命令的输出中，查找 `"We are completely uploaded and fine"` 这一短语。此短语表示文件已成功上传。运行导入作业后，您的用户池不会将信息保留在导入文件中。在它们完成或过期后，Amazon Cognito 会删除上传的 CSV 文件。
#### 描述用户导入任务
要获取用户导入任务的描述，请使用以下命令，其中{{USER\_POOL\_ID}}是您的用户池 ID，{{JOB\_ID}}是您创建用户导入任务时返回的任务 ID。
```
aws cognito-idp describe-user-import-job --user-pool-id "{{USER_POOL_ID}}" --job-id "{{JOB_ID}}"
```
**Example 示例响应：**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl": "{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn":"{{ROLE_ARN}}",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
在前面的示例输出中，{{PRE\_SIGNED\_URL}}是您将 CSV 文件上传到的网址。{{ROLE\_ARN}}是您在创建角色时收到的 CloudWatch 日志角色 ARN。
#### 列出用户导入任务
要列出用户导入任务，请使用以下命令：
```
aws cognito-idp list-user-import-jobs --user-pool-id "{{USER_POOL_ID}}" --max-results 2
```
**Example 示例响应：**
```
{
"UserImportJobs": [
{
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl":"{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn":"{{ROLE_ARN}}",
"FailedUsers": 0,
"CreationDate": 1470957431.965
},
{
"CompletionDate": 1470954227.701,
"StartDate": 1470954226.086,
"Status": "Failed",
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "{{JOB_NAME}}",
"CompletionMessage": "Too many users have failed or been skipped during the import.",
"JobId": "{{JOB_ID}}",
"PreSignedUrl":"{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn":"{{ROLE_ARN}}",
"FailedUsers": 5,
"CreationDate": 1470953929.313
}
],
"PaginationToken": "{{PAGINATION_TOKEN}}"
}
```
任务按创建日期 (从近到远) 排列。第二个任务之后的{{PAGINATION\_TOKEN}}字符串表示此列表命令还有其他结果。要列出更多结果，请使用 `--pagination-token` 选项，如下所示：
```
aws cognito-idp list-user-import-jobs --user-pool-id "{{USER_POOL_ID}}" --max-results 10 --pagination-token "{{PAGINATION_TOKEN}}"
```
#### 启动用户导入任务
要启动用户导入任务，请使用以下命令：
```
aws cognito-idp start-user-import-job --user-pool-id "{{USER_POOL_ID}}" --job-id "{{JOB_ID}}"
```
每个账户每次只能有一个导入任务处于活动状态。
**Example 示例响应：**
```
{
"UserImportJob": {
"Status": "Pending",
"StartDate": 1470957851.483,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl":"{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn": "{{ROLE_ARN}}",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
#### 停止用户导入任务
要停止正在进行的用户导入任务，请使用以下命令。停止任务后，无法重新启动该任务。
```
aws cognito-idp stop-user-import-job --user-pool-id "{{USER_POOL_ID}}" --job-id "{{JOB_ID}}"
```
**Example 示例响应：**
```
{
"UserImportJob": {
"CompletionDate": 1470958050.571,
"StartDate": 1470958047.797,
"Status": "Stopped",
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"SkippedUsers": 0,
"JobName": "{{JOB_NAME}}",
"CompletionMessage": "The Import Job was stopped by the developer.",
"JobId": "{{JOB_ID}}",
"PreSignedUrl":"{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn": "{{ROLE_ARN}}",
"FailedUsers": 0,
"CreationDate": 1470957972.387
}
}
```
## 在 CloudWatch 控制台中查看用户池导入结果
您可以在 Amazon CloudWatch 控制台中查看导入任务的结果。
**Topics**
+ [查看结果](#cognito-user-pools-using-import-tool-viewing-the-results)
+ [解析结果](#cognito-user-pools-using-import-tool-interpreting-the-results)
### 查看结果
以下步骤介绍了如何查看用户池导入结果。
**查看用户池导入结果的步骤**
1. 登录 AWS 管理控制台 并打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。
1. 选择 **Logs (日志)**。
1. 为用户池导入任务选择日志组。日志组名称的形式为 `/aws/cognito/userpools/{{USER_POOL_ID}}/{{USER_POOL_NAME}}`。
1. 为刚运行的用户导入任务选择日志。日志名称的格式为{{JOB\_ID}}/{{JOB\_NAME}}。日志中的结果按行号引用用户。日志中不会写入用户数据。对于每个用户，都将出现类似于以下内容的行：
+ `[SUCCEEDED] Line Number 5956 - The import succeeded.`
+ `[SKIPPED] Line Number 5956 - The user already exists.`
+ `[FAILED] Line Number 5956 - The User Record does not set any of the auto verified attributes to true. (Example: email_verified to true).`
### 解析结果
成功导入的用户的状态设置为 “PasswordReset”。
在以下情况下，将不会导入用户，但导入任务将继续：
+ 自动验证属性未设置为 `true`。
+ 用户数据与架构不匹配。
+ 由于内部错误，无法导入用户。
在以下情况下，导入任务将失败：
+ 无法担任 CloudWatch Amazon Logs 角色，该角色的访问策略不正确，或者已被删除。
+ 用户池已删除。
+ Amazon Cognito 无法解析 .csv 文件。
## 要求导入的用户重置密码
如果您的用户池仅提供基于密码的登录，则在导入用户后，用户必须重置其密码。他们第一次登录时可以输入*任何*密码。Amazon Cognito 会在 API 响应您的应用程序的登录请求时提示他们输入新密码。
如果您的用户池具有无密码身份验证因素，Amazon Cognito 会默认采用适用于导入的用户的身份验证因素。他们不会被提示输入新密码，并且可以立即使用无密码电子邮件或短信 OTP 登录。您也可以提示用户设置密码，以便他们可以完成其他登录方法，例如用户名密码和通行密钥。以下条件适用于导入用户后的无密码登录。
1. 您必须使用与可用无密码登录因素相对应的属性导入用户。如果用户可以使用电子邮件地址登录，则必须导入 `email` 属性。如果是电话号码，则必须导入 `phone_number` 属性。如果两者兼而有之，则为任一属性导入一个值。
1. 通常，用户在必须重置其密码的 `RESET_REQUIRED` 状态下导入。如果用户在导入后能够使用无密码因素登录，则 Amazon Cognito 会将其状态设置为 `CONFIRMED`。
有关无密码身份验证的更多信息，包括如何设置无密码身份验证以及如何在应用程序中构造身份验证流程，请参阅[使用 Amazon Cognito 用户池进行身份验证](authentication.md)。
以下过程描述了您导入 CSV 文件后，处于 `RESET_REQUIRED` 状态的本地用户在自定义构建的登录机制中的用户体验。如果您的用户通过托管登录进行登录，请让他们选择**忘记密码？**选项，提供他们的电子邮件或短信中的代码，然后设置密码。
**要求导入的用户重置密码**
1. 在您的应用程序中，通过 `InitiateAuth` 使用随机密码以静默方式为当前用户尝试登录。
1. 启用了 `PreventUserExistenceErrors` 时，Amazon Cognito 返回 `NotAuthorizedException`。否则返回 `PasswordResetRequiredException`。
1. 您的应用程序发出 `ForgotPassword` API 请求并重置用户的密码。
1. 应用程序在 `ForgotPassword` API 请求中提交用户名。
1. Amazon Cognito 向经过验证的电子邮件或电话发送代码。目标取决于您在 CSV 文件中为 `email_verified` 和 `phone_number_verified` 提供的值。对 `ForgotPassword` 请求的响应指明了代码的目标。
**注意**
必须将您的用户池配置为验证电子邮件或电话号码。有关更多信息，请参阅 [注册并确认用户账户](signing-up-users-in-your-app.md)。
1. 您的应用程序向用户显示一条消息，以检查发送代码的位置，并提示用户输入代码和新密码。
1. 用户在应用程序中输入代码和新密码。
1. 应用程序在 `ConfirmForgotPassword` API 请求中提交代码和新密码。
1. 您的应用程序重定向用户以进行登录。
## 使用密码哈希导入用户
当您将用户从现有身份验证系统迁移到 Amazon Cognito 时，您可以导入他们的密码哈希及其用户属性。然后，您的用户可以使用其现有密码立即登录，无需重置密码。用户首次登录后，Amazon Cognito 会透明地将其凭证迁移到原生 Amazon Cognito 身份验证系统。
**重要**
目前，并非所有用户池都可以使用密码哈希导入。密码哈希导入需要具有增强功能和可扩展性的现代 Amazon Cognito 基础设施。一些用户池仍在以前的基础架构上，他们 AWS 会将其升级到新的基础架构，从而解锁此功能。在 Amazon Cognito 控制台中，符合条件的用户池在创建导入任务时会显示密码哈希算法选项，不符合条件的用户池不显示此选项。有关更多信息，请参阅安全博客中的 [Amazon Cognito 利用下一代基础设施解锁高级功能](https://aws.amazon.com/blogs/security/amazon-cognito-unlocks-advanced-capabilities-with-next-generation-infrastructure/)。 AWS
### 密码哈希导入的工作原理
通过密码哈希导入，您可以迁移用户，同时保留他们使用现有密码登录的能力。导入过程如下所示：
1. 您可以创建导入任务并指定源系统用于创建密码哈希的密码哈希算法。
1. 您可以在 CSV 文件中加入带有每个用户的密码哈希值的`password_hash`列。
1. Amazon Cognito 导入带有密码哈希值的用户，并创建具有状态的用户。`CONFIRMED`用户可以立即登录。
1. 当用户首次登录时，Amazon Cognito 会根据导入的哈希值验证其密码。成功验证后，Amazon Cognito 会将用户的证书迁移到本机身份验证系统。
1. 所有后续登录都使用原生 Amazon Cognito 身份验证系统。
**重要**
单个导入任务中的所有密码哈希值都必须使用相同的算法。创建导入任务时，可以在作业级别指定算法。
**注意**
在用户完成首次登录且 Amazon Cognito 迁移其证书之前，您无法对该用户使用安全远程密码 (SRP) 身份验证。对于已导入密码哈希但尚未登录的用户，请使用`USER_PASSWORD_AUTH`或`ADMIN_USER_PASSWORD_AUTH`流程。
### 支持的密码哈希算法
Amazon Cognito 支持以下密码哈希算法进行导入：
`BCRYPT`
bcrypt 自适应哈希函数。Amazon Cognito 从哈希字符串中提取所有必需的参数（盐、成本因子）。
**Format**: `$2$[cost]$[22-char salt][31-char hash]`
**示例**：`$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6`
**最大成本系数：**10
`SCRYPT`
基于 scrypt 密码的密钥派生函数。Amazon Cognito 从哈希字符串中提取所有必需的参数。
**Format**: `N$r$p$hexSalt$hexHash`
**示例**：`65536$8$1$304dbaef7c5e828dc19c98f0600d18fe$4f69c498c12cd102d057356facf8d77e8d42407090491ea32c5b038f5a18c099`
**最大参数：**N（CPU/memory 成本）= 65536，r（区块大小）= 8，p（并行度）= 1
`ARGON2ID`
Argon2ID 的密码哈希算法。Amazon Cognito 从哈希字符串中提取所有必需的参数。
**Format**: `$argon2id$v=N$m=M,t=T,p=P$salt$hash`
**示例**：`$argon2id$v=19$m=19456,t=2,p=1$ko/G5o1ms+ML08P95sQ8DA$AkVbvWSOqz7Hs3qthhWKxicOWnGLN+MBmpwc3emi5VA`
**最大参数：**m（以 kiB 为单位的内存）= 19456，t（迭代）= 2，p（并行度）= 1
`PBKDF2_SHA256`
Password-Based 密钥派生函数 2 带有。 SHA-256Amazon Cognito 从哈希字符串中提取所有必需的参数。
**Format**: `$pbkdf2-sha256$iterations$salt$hash`
**示例**：`$pbkdf2-sha256$600000$1XZlmwLQ2hhM3JYuCPiArQ$Pfheg9Zi/v5lXU4yyLA0WFUYEd/rlaVbzrM9oMD6IrA`
**最大迭代次数：600000**
**注意**
所有支持的算法都是自描述的，这意味着 Amazon Cognito 可以直接从哈希字符串中提取所有必需的参数（例如盐分、成本因子和迭代）。您只需在创建导入任务时指定算法名称即可。
如果您的密码哈希的参数值超过了上面列出的最大界限，则该用户的导入将失败。在导入之前，请检查源系统的密码哈希配置，以确保兼容性。
### 在 CSV 文件中添加密码哈希值
当您下载用于用户导入的 CSV 模板时，该模板包含一`password_hash`列。在此列中填入要使用现有密码导入的用户的密码哈希值。
**密码哈希导入的 CSV 格式化规则**
+ 当您的导入任务指定密码哈希算法时，该`password_hash`列为必填项。如果您将特定用户的值留空，Amazon Cognito 会导入该用户而不输入密码，并将该用户设置为该`RESET_REQUIRED`状态。
+ 如果您的导入任务指定了密码哈希算法，但您的 CSV 文件不包含`password_hash`列，则该任务将失败。
+ 如果密码哈希值格式错误或与指定算法的预期格式不匹配，则该用户的导入将失败。Amazon Cognito 不会创建用户，而是将失败记录在您的亚马逊 CloudWatch 日志日志中。
+ 密码哈希值区分大小写。确保它们与算法期望的格式完全匹配。
**Example 带有密码哈希值的 CSV 示例**
以下示例显示了一个 CSV 文件，该文件导入具有 bcrypt 密码哈希值的用户：
```
cognito:username,email,email_verified,phone_number,phone_number_verified,password_hash
alejandro_rosalez,alejandro_rosalez@example.com,TRUE,+12345550100,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6
mary_major,mary_major@example.com,TRUE,+12345550199,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6
```
### 使用密码哈希创建导入任务 (AWS CLI)
要使用密码哈希导入用户，必须在创建导入任务时指定密码哈希算法。导入任务中的所有用户都必须使用相同的算法。
使用以下 AWS Command Line Interface 命令创建带有密码哈希值的导入任务。该`--password-hashing-algorithm`参数指定用于在 CSV 文件中创建密码哈希的算法。
```
aws cognito-idp create-user-import-job \
--job-name "{{JOB_NAME}}" \
--user-pool-id "{{USER_POOL_ID}}" \
--cloud-watch-logs-role-arn "{{ROLE_ARN}}" \
--password-hashing-algorithm {{BCRYPT}}
```
{{BCRYPT}}替换为支持的算法之一：`BCRYPT``SCRYPT`、`ARGON2ID`、或`PBKDF2_SHA256`。
**Example 示例响应**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl": "{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn": "{{ROLE_ARN}}",
"PasswordHashingAlgorithm": "BCRYPT",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
响应中包含确认您指定的算法的`PasswordHashingAlgorithm`字段。将您的 CSV 文件上传到预签名 URL，然后按中所[上传 CSV 文件](#cognito-user-pools-using-import-tool-cli-uploading-csv-file)述启动作业。
### 导入密码哈希后的用户体验
使用密码哈希值导入的用户具有以下体验：
+ **立即登录：**用户可以在导入后立即使用其现有密码登录。用户不会收到重置密码的提示。
+ **用户状态：**Amazon Cognito 为这些用户创建的`CONFIRMED`状态为，而不是。`RESET_REQUIRED`
+ **透明迁移：**当用户首次登录时，Amazon Cognito 会根据导入的哈希值验证他们的密码。成功验证后，Amazon Cognito 会将其凭证迁移到原生身份验证系统。所有后续登录都使用本机系统。
+ **初始登录延迟：**使用导入密码哈希值的用户首次登录所花费的时间可能比后续登录的时间稍长一些。Amazon Cognito 必须根据导入的哈希值验证密码，并将证书迁移到本机身份验证系统。
+ **密码重置：**如果用户在首次登录之前重置了密码，则使用原生 Amazon Cognito 身份验证系统将使用原生 Amazon Cognito 身份验证系统将他们导入的密码哈希值替换为新密码。
### 密码哈希导入错误疑难解答
如果用户的密码哈希导入失败，Amazon Cognito 会将失败记录在您的亚马逊 CloudWatch 日志日志中。常见的错误场景包括：
格式错误的哈希
密码哈希值与指定算法的预期格式不匹配。验证哈希格式是否正确且与中列出的格式之一相匹配[支持的密码哈希算法](#cognito-user-pools-import-password-hash-algorithms)。
参数超出界限
密码哈希包含超过最大允许值的参数值（例如成本系数或迭代次数）。对于哈希值不兼容的用户，请选择以下选项之一：
+ 将该`password_hash`字段留空，即可导入那些没有密码哈希的用户。Amazon Cognito 将他们设置为`RESET_REQUIRED`状态，他们必须在首次登录时重置密码。
+ 使用[用户迁移 Lambda 触发器](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html)在登录时迁移这些用户，而不是通过 CSV 导入。
+ 在停用源系统之前，请在用户登录您的现有系统时使用兼容的参数重新对密码进行哈希处理。
算法不匹配
密码哈希是使用与导入任务中指定的算法不同的算法创建的。单个导入任务中的所有哈希值都必须使用相同的算法。如果您的用户使用不同的算法，请为每种算法创建单独的导入任务。
缺少 password\_hash 列
您在创建任务时指定了密码哈希算法，但您的 CSV 文件不包含该`password_hash`列。将该列添加到 CSV 文件中，或者在不指定算法的情况下创建新作业。
当用户的密码哈希导入失败时，Amazon Cognito 不会创建该用户。继续处理导入任务中的其他用户。查看您的 Amazon Logs 日 CloudWatch 志，确定哪些用户失败了，以及每次失败的原因。
### 密码哈希导入的安全注意事项
Amazon Cognito 对导入的密码哈希应用了额外的安全措施：
+ **双重哈希：**无论原始算法的强度如何，Amazon Cognito 都会重新哈希所有导入的密码哈希，并在存储之前增加一层加密保护。
+ **自动迁移：**成功进行首次身份验证后，Amazon Cognito 会将用户的凭证迁移到 Amazon Cognito 使用的本机安全远程密码 (SRP) 协议。这样可以确保所有用户最终都使用原生的高安全性身份验证机制。
+ **数据清理：**导入任务完成后，Amazon Cognito 会从临时存储中删除上传的包含密码哈希的 CSV 文件。
**重要**
将包含密码哈希的 CSV 文件视为敏感数据。在运输途中对其进行保护，并在导入完成后将其安全删除。