通过 CSV 文件将用户导入用户池中

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

默认情况下，导入过程会为除密码之外的所有用户属性设置值。这意味着，用户必须在首次登录时更改密码。使用此方法导入用户时，用户处于 RESET_REQUIRED 状态。

或者，您可以使用用户的现有密码哈希值导入用户。当您在创建导入任务期间指定密码哈希算法并在 CSV 文件中包含密码哈希时，Amazon Cognito 会使用用户的现有密码导入。这些用户以CONFIRMED状态创建，无需重置密码即可立即登录。有关更多信息，请参阅 使用密码哈希导入用户。

从 CSV 导入用户最省力的方法是在用户池中激活无密码登录。借助电子邮件地址和电话号码属性以及正确的用户池配置，用户可以在导入作业完成后立即使用电子邮件或短信一次性密码（OTP）登录。有关更多信息，请参阅 要求导入的用户重置密码。

您也可以使用 AdminSetUserPassword API 请求，将 Permanent 参数设置为 true 来设置用户的密码。CSV 导入不会计入用户池中的计费月活跃用户（MAU）。但密码重置操作会生成 MAU。要在导入大量可能不会立即处于活动状态的带密码用户时控制成本，请将您的应用程序设置为在用户登录并收到 RESET_REQUIRED 质询时提示他们输入新密码。

创建日 CloudWatch 志 IAM 角色

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

创建用户导入 CSV 文件

您必须先创建逗号分隔值（CSV，Comma-Separated Value）文件，在其中包含要导入的用户及其属性，然后才能将现有用户导入用户池中。从用户池中，您可以检索其标头反映了您的用户池的属性架构的用户导入文件。然后，您可以插入符合 设置 CSV 文件的格式 中的格式要求的用户信息。

下载 CSV 文件标头（控制台）

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

下载 CSV 文件头 (Amazon 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 文件，以使文件包含此标头和用户的属性值，并根据以下规则设置格式：

以下列表是没有自定义属性的用户池的 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 控制台和 Amazon Command Line Interface (Amazon CLI) 创建和运行用户池导入任务。

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

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

导入用户 (Amazon CLI)

以下 CLI 命令可用于将用户导入到用户池：

要获取这些命令的命令行选项列表，请使用 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 值当中的其中一个值：

上传 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"

{
    "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 文件上传到的 URL。ROLE_ARN是您在创建角色时收到的 CloudWatch 日志角色 ARN。

列出用户导入任务

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

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 控制台中查看用户池导入结果

您可以在亚马逊 CloudWatch 控制台中查看导入任务的结果。

查看结果

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

解析结果

成功导入的用户的状态设置为 “PasswordReset”。

在以下情况下，将不会导入用户，但导入任务将继续：

在以下情况下，导入任务将失败：

要求导入的用户重置密码

如果您的用户池仅提供基于密码的登录，则在导入用户后，用户必须重置其密码。他们第一次登录时可以输入任何密码。Amazon Cognito 会在 API 响应您的应用程序的登录请求时提示他们输入新密码。

如果您的用户池具有无密码身份验证因素，Amazon Cognito 会默认采用适用于导入的用户的身份验证因素。他们不会被提示输入新密码，并且可以立即使用无密码电子邮件或短信 OTP 登录。您也可以提示用户设置密码，以便他们可以完成其他登录方法，例如用户名密码和通行密钥。以下条件适用于导入用户后的无密码登录。

有关无密码身份验证的更多信息，包括如何设置无密码身份验证以及如何在应用程序中构造身份验证流程，请参阅使用 Amazon Cognito 用户池进行身份验证。

以下过程描述了您导入 CSV 文件后，处于 RESET_REQUIRED 状态的本地用户在自定义构建的登录机制中的用户体验。如果您的用户通过托管登录进行登录，请让他们选择忘记密码？选项，提供他们的电子邮件或短信中的代码，然后设置密码。

使用密码哈希导入用户

当您将用户从现有身份验证系统迁移到 Amazon Cognito 时，您可以导入他们的密码哈希值及其用户属性。然后，您的用户可以立即使用其现有密码登录，无需重置密码。用户首次登录后，亚马逊 Cognito 会透明地将其凭证迁移到原生亚马逊 Cognito 身份验证系统。

密码哈希导入的工作原理

通过密码哈希导入，您可以迁移用户，同时保留他们使用现有密码登录的能力。导入过程如下所示：

支持的密码哈希算法

亚马逊 Cognito 支持以下密码哈希算法进行导入：

如果您的密码哈希值的参数值超过了上面列出的最大边界，则该用户的导入将失败。在导入之前，请检查源系统的密码哈希配置以确保兼容性。

将密码哈希值添加到 CSV 文件中

当您下载用于用户导入的 CSV 模板时，该模板包含一password_hash列。使用要使用现有密码导入的用户的密码哈希值填充此列。

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

使用密码哈希创建导入任务 (Amazon CLI)

要使用密码哈希导入用户，必须在创建导入任务时指定密码哈希算法。导入任务中的所有用户都必须使用相同的算法。

使用以下 Amazon 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替换为支持的算法之一：BCRYPTSCRYPT、ARGON2ID、或PBKDF2_SHA256。

{
    "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 文件述开始作业。

导入密码哈希后的用户体验

使用密码哈希值导入的用户具有以下体验：

解决密码哈希导入错误

如果用户的密码哈希导入失败，Amazon Cognito 会在您的亚马逊 CloudWatch 日志中记录失败。常见的错误场景包括：

当用户的密码哈希导入失败时，Amazon Cognito 不会创建用户。继续处理导入任务中的其他用户。查看您的亚马逊 CloudWatch 日志以确定哪些用户失败以及每次失败的原因。

密码哈希导入的安全注意事项

亚马逊 Cognito 对导入的密码哈希应用了额外的安全措施：