创建 “日 CloudWatch 志” IAM 角色创建用户导入CSV文件创建并运行用户导入任务查看导入任务结果要求导入的用户重置密码

将用户从CSV文件导入用户池

如果您有外部身份存储，并且有时间为新的本地用户准备用户池，那么从逗号分隔值 (CSV) 文件中批量导入用户可能是迁移到 Amazon Cognito 用户池的省力、低成本的选择。CSV文件导入是下载并填充模板文件，然后在导入任务中将该文件移交给用户池的过程。您可以使用CSV导入来快速创建测试用户。您还可以通过编程方式在文件中填充对外部身份存储的读取API请求，然后将其详细信息和属性解析为对文件的写入操作。

导入过程会设置所有用户属性的值，不过 password 除外。不支持导入密码，因为安全妥善做法要求密码不能为纯文本，而我们不支持导入哈希。这意味着，用户必须在首次登录时更改密码。使用此方法导入用户时，您的用户RESET_REQUIRED处于状态。

您可以使用以下方式设置用户的密码 AdminSetUserPasswordAPI请求将Permanent参数设置为true。CSVimport 不会计入用户池中按月计费的活跃用户 (MAUs)。但是，确实会生成密码重置操作。MAUs要在导入大量可能不会立即处于活动状态的用户时管理成本，请将您的应用程序设置为在用户登录并接受RESET_REQUIRED质询时提示他们输入新密码。

注意

每个用户的创建日期就是将该用户导入用户池中的日期。创建日期不是导入的属性之一。

创建用户导入任务的步骤

在 AWS Identity and Access Management (IAM) 控制台中创建 Amazon CloudWatch Logs 角色。
创建用户导入 .csv 文件。
创建并运行用户导入任务。
上传用户导入 .csv 文件。
启动并运行用户导入任务。
CloudWatch 用于查看事件日志。
要求导入的用户重置密码。

创建 “日 CloudWatch 志” IAM 角色

如果你使用的是 Amazon Cognito CLI 或API，那么你需要创建一个角色。 CloudWatch IAM以下过程介绍如何创建一个IAM角色，Amazon Cognito 可以使用该角色将导入任务的结果写入日志。 CloudWatch

注意

在 Amazon Cognito 控制台中创建导入任务时，您可以同时创建该IAM角色。当您选择创建新IAM角色时，Amazon Cognito 会自动将相应的信任策略和IAM策略应用于该角色。

要为用户池导入创建 CloudWatch 日志IAM角色（AWS CLI，API）

登录 AWS Management Console 并打开IAM控制台，网址为https://console.aws.amazon.com/iam/。
为创建新IAM角色 AWS 服务。有关详细说明，请参阅《AWS Identity and Access Management 用户指南》中的为 AWS 服务创建一个角色。
1. 当您为 Trusted entity type（可信实体类型）选择 Use case（使用案例）时，请选择任意服务。Amazon Cognito 目前未在服务使用案例中列出。
2. 在 Add permissions（添加权限）屏幕中，选择 Create policy（创建策略）并插入以下策略声明。Replace（替换） REGION 例如 AWS 区域，使用您的用户池中的us-east-1。Replace（替换） ACCOUNT 例如，使用您的 AWS 账户身份证111122223333。
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents"
            ],
            "Resource": [
                "arn:aws:logs:REGION:ACCOUNT:log-group:/aws/cognito/*"
            ]
        }
    ]    
}
```
由于您在创建角色时没有选择 Amazon Cognito 作为可信实体，因此您现在必须手动编辑该角色的信任关系。从IAM控制台的导航窗格中选择 “角色”，然后选择您创建的新角色。
选择 Trust relationships（信任关系）选项卡。
选择编辑信任策略。

将以下策略声明粘贴到 Edit trust policy（编辑信任策略）中，替换任何现有文本：


{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Service": "cognito-idp.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
        ]
    }

选择更新策略。
注意这个角色ARN。您将在创建导入任务ARN时提供。

创建用户导入CSV文件

在将现有用户导入用户池之前，必须创建一个包含要导入的用户及其属性的逗号分隔值 (CSV) 文件。从用户群体中，您可以检索其标头反映了您的用户群体的属性架构的用户导入文件。然后，您可以插入符合格式化CSV文件中的格式要求的用户信息。

下载CSV文件头（控制台）

使用以下步骤下载CSV头文件。

下载CSV文件头

转到 Amazon Cognito 控制台。系统可能会提示您输入 AWS 凭证。
选择 User Pools（用户池）。
从列表中选择现有用户池。
选择用户选项卡。
在 Import users（导入用户）部分中，选择 Create an import job（创建导入作业）。
在 “上传” 下CSV，选择 template.csv 链接并下载CSV文件。

正在下载CSV文件头 (AWS CLI)

要获取正确标题的列表，请运行以下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文件，使其包含此标题和用户的属性值，并按照以下规则进行格式化：

注意

有关属性值（如电话号码的正确格式）的更多信息，请参阅使用用户属性。

文件的第一行是已下载的包含用户属性名称的标头行。
CSV文件中列的顺序无关紧要。
第一行之后的每一行都包含用户的属性值。
标头中的所有列都必须存在，但您不需要在每一列中提供值。
以下属性为必需属性：
- cognito:username
- cognito:mfa_enabled
- email_verified 或 phone_number_verified
  - 每个用户至少有一个自动验证属性必须为 true。自动验证的属性是新用户加入您的用户群体时，Amazon Cognito 自动向其发送验证码的电子邮件地址或电话号码。
  - 用户池必须至少有一个自动验证属性，要么是 email_verified，要么是 phone_number_verified。如果用户池没有自动验证属性，则导入任务不会启动。
  - 如果用户池只有一个自动验证属性，则该属性必须针对每个用户进行验证。例如，如果用户池只有 phone_number 为自动验证属性，则每个用户的 phone_number_verified 值都必须为 true。
  注意
  对于重置其密码的用户，用户必须拥有经过验证的电子邮件或电话号码。Amazon Cognito 将包含重置密码代码的消息发送到文件中指定的电子邮件或电话号码。CSV如果消息发送到电话号码，则通过SMS消息发送。有关更多信息，请参阅在注册时验证联系人信息。
- 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) 设置为必填项，则此字段必须true适用于所有用户。如果您已设置MFA为关闭，则此字段必须false适用于所有用户。如果您已设置MFA为可选，则此字段可以是true或false，但不能为空。
最大长度为 16000 个字符。
最大CSV文件大小为 100 MB。
文件中的最大行（用户）数为 500000。此最大值不包括标题行。
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创建和运行用户池导入任务。

主题

从CSV文件导入用户（控制台）
导入用户（AWS CLI）

从CSV文件导入用户（控制台）

以下过程介绍如何从CSV文件中导入用户。

从CSV文件导入用户（控制台）

转到 Amazon Cognito 控制台。系统可能会提示您输入 AWS 凭证。
选择 User Pools（用户池）。
从列表中选择现有用户池。
选择用户选项卡。
在 Import users（导入用户）部分中，选择 Create an import job（创建导入作业）。
在 Create import job（创建导入作业）页面上，输入 Job name（作业名称）。
选择 “创建新IAM角色” 或 “使用现有IAM角色”。
1. 如果您选择了创建新IAM角色，请输入新角色的名称。Amazon Cognito 将自动创建具有正确权限和信任关系的角色。创建导入任务的IAM委托人必须具有创建IAM角色的权限。
2. 如果您选择了使用现有IAM角色，请从角色选择下的列表中选择一个IAM角色。此角色必须具有创建 “日 CloudWatch 志” IAM 角色中所述的权限和信任策略。
选择 Create job（创建作业）可提交作业，但稍后再启动。选择 Create and start job（创建并启动作业）可提交您的作业并立即启动。
如果您创建了作业但未启动作业，则可以稍后再启动。在 Users（用户）选项卡下的 Import users（导入用户）中，选择导入作业，然后选择 Start（开始）。您也可以通过以下方式提交StartUserImportJobAPI请求 AWS SDK。
在 Users（用户）选项卡下的 Import users（导入用户）中，监控用户导入作业的进度。如果您的作业不成功，则可以选择 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 角色：


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。

例示例响应:


{
    "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" 这一短语。此短语表示文件已成功上传。

描述用户导入任务

要获取用户导入任务的描述，请使用以下命令，其中 USER_POOL_ID 是您的用户池 ID，以及 JOB_ID 是您创建用户导入任务时返回的任务 ID。


aws cognito-idp describe-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

例示例响应:


{
    "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 是你URL将CSV文件上传到的。这些区域有：ROLE_ARN 是您在创建角色时获得ARN的 “ CloudWatch 日志” 角色。

列出用户导入任务

要列出用户导入任务，请使用以下命令：


aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 2

例示例响应:


{
    "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"

每个账户每次只能有一个导入任务处于活动状态。

例示例响应:


{
    "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"

例示例响应:


{
    "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 控制台中查看导入任务的结果。

主题

查看结果
解析结果

查看结果

以下步骤介绍了如何查看用户池导入结果。

查看用户池导入结果的步骤

登录 AWS Management Console 并打开 CloudWatch 控制台，网址为https://console.aws.amazon.com/cloudwatch/。
选择 Logs (日志)。
为用户池导入任务选择日志组。日志组名称的形式为 /aws/cognito/userpools/USER_POOL_ID/USER_POOL_NAME。
为刚运行的用户导入任务选择日志。日志名称的格式为 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 文件。

要求导入的用户重置密码

每个导入的用户第一次登录并输入任意密码时，系统都会要求其输入新密码。以下过程描述了导入CSV文件后在自定义应用程序中使用本地用户的用户体验。如果您的用户使用托管 UI 登录，Amazon Cognito 会在其首次登录时提示他们设置新密码。

要求导入的用户重置密码

在您的应用程序中，通过 InitiateAuth 使用随机密码以静默方式为当前用户尝试登录。
启用了 PreventUserExistenceErrors 时，Amazon Cognito 返回 NotAuthorizedException。否则返回 PasswordResetRequiredException。
您的应用程序发出ForgotPasswordAPI请求并重置用户的密码。
1. 应用程序在ForgotPasswordAPI请求中提交用户名。
2. Amazon Cognito 向经过验证的电子邮件或电话发送代码。目的地取决于您在CSV文件phone_number_verified中为email_verified和提供的值。对 ForgotPassword 请求的响应指明了代码的目标。
  
  注意
  必须将您的用户群体配置为验证电子邮件或电话号码。有关更多信息，请参阅注册并确认用户账户。
3. 您的应用程序向用户显示一条消息，以检查发送代码的位置，并提示用户输入代码和新密码。
4. 用户在应用程序中输入代码和新密码。
5. 应用程序在ConfirmForgotPasswordAPI请求中提交代码和新密码。
6. 您的应用程序重定向用户以进行登录。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

用户迁移触发器导入

Attributes

将用户从CSV文件导入用户池

注意

创建用户导入任务的步骤

更多资源

主题

创建 “日 CloudWatch 志” IAM 角色

注意

要为用户池导入创建 CloudWatch 日志IAM角色（AWS CLI，API）

创建用户导入CSV文件

下载CSV文件头（控制台）

下载CSV文件头

正在下载CSV文件头 (AWS CLI)

格式化CSV文件

注意

注意

创建并运行 Amazon Cognito 用户池导入任务

主题

从CSV文件导入用户（控制台）

从CSV文件导入用户（控制台）

导入用户（AWS CLI）

创建用户导入任务

例 示例响应:

用户导入任务的状态值

上传CSV文件

描述用户导入任务

例 示例响应:

列出用户导入任务

例 示例响应:

启动用户导入任务

例 示例响应:

停止用户导入任务

例 示例响应:

在 CloudWatch 控制台中查看用户池导入结果

主题

查看结果

查看用户池导入结果的步骤

解析结果

要求导入的用户重置密码

要求导入的用户重置密码

注意

例示例响应:

例示例响应:

例示例响应:

例示例响应:

例示例响应: