本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 管理用户池中的用户
创建用户群体后，您可以创建、确认和管理用户账户。借助 Amazon Cognito 用户池组，您可以通过将 IAM 角色映射到组来管理您的用户及其对资源的访问。
管理 Amazon Cognito 用户池中的用户涉及各种配置选项和管理任务。用户池可以扩展到数百万用户。这种规模的用户目录需要同样可扩展和可重复的管理工具。您可能需要创建许多用户配置文件、管理不活跃的用户、生成治理和合规报告，或者设置自助工具，让用户自行处理大部分工作。创建用户池后，您可以控制用户如何注册和确认账户，包括要求验证电子邮件或电话号码。管理员还可以直接创建用户账户并自定义欢迎消息和密码要求。
用户池有用户组，您可以根据用户的组成员资格来管理对资源的访问权限。您可以为这些组分配 IAM 角色，从而使用身份池来管理对 AWS 服务的访问权限。ID 令牌和访问令牌中均存在用户的组成员资格。有了这些信息，您就可以在应用程序运行时或使用诸如 Amazon Verified Permissions 之类的策略引擎作出访问控制决策。
用户池通常有许多用户。您会发现自己经常需要搜索和更新用户账户。Amazon Cognito 控制台和 API 支持根据用户名、电子邮件和电话号码等标准属性查询用户。管理员还可以重置密码、禁用账户和查看用户事件历史记录。
为了迁移现有用户数据，Amazon Cognito 可以选择从 CSV 文件导入用户，也可以在用户首次登录时使用 [Lambda 触发器](user-pool-lambda-migrate-user.md)自动迁移用户。这些选项支持用户从其他用户目录转换到您的用户池。
您可以使用用户池中的用户管理特征来精细控制用户生命周期和身份验证体验。自助注册、管理员创建的账户、组和迁移工具相结合，使 Amazon Cognito 用户池成为灵活的用户目录。
**Topics**
+ [配置用户创建策略](user-pool-settings-admin-create-user-policy.md)
+ [注册并确认用户账户](signing-up-users-in-your-app.md)
+ [以管理员身份创建用户账户](how-to-create-user-accounts.md)
+ [向用户池添加组](cognito-user-pools-user-groups.md)
+ [管理和搜索用户账户](how-to-manage-user-accounts.md)
+ [密码、账户恢复和密码策略](managing-users-passwords.md)
+ [将用户导入一个用户池](cognito-user-pools-import-users.md)
+ [使用用户属性](user-pool-settings-attributes.md)
# 配置用户创建策略
您的用户池可以允许用户注册，您也可以以管理员身份创建用户。您还可以控制注册后的验证和确认过程由用户掌控的程度。例如，您可能需要审查注册并根据外部验证流程接受注册。此配置，或*管理员创建用户策略*，还可设置用户无法再确认其用户账户之前的时间长度。
作为软件的客户身份和访问管理（CIAM）平台，Amazon Cognito 可以满足公众客户的需求。接受注册并拥有应用程序客户端的用户池，无论有没有托管登录，都可以为互联网上知道您的可公开发现的应用程序客户端 ID 并请求注册的任何人创建用户配置文件。注册的用户配置文件可接收访问和身份令牌，还可以访问您为应用程序授权的资源。在用户池中激活注册之前，请查看您的选项并确保配置符合您的安全标准。请按照以下步骤所述，谨慎设置**启用自行注册**和 `AllowAdminCreateUserOnly`。
------
#### [ AWS 管理控制台 ]
用户池的**注册**菜单包含在用户池中注册和以管理员身份创建用户的一些设置。
**配置注册体验**
1. 在 **Cognito 辅助验证和确认**中，选择是否**允许 Cognito 自动发送消息以进行验证和确认**。启用此设置后，Amazon Cognito 会向新用户发送电子邮件或短信，其中包含他们必须向您的用户池出示的代码。这将确认他们对电子邮件地址或电话号码的所有权，将等效属性设置为已验证，并确认用于登录的用户账户。您选择的**要验证的属性**将决定验证消息的传送方式和目的地。
1. 在创建用户时，**验证属性更改**并不重要，但与属性验证有关。可以允许已更改但尚未验证其[登录属性的](user-pool-settings-attributes.md#user-pool-settings-aliases.title)用户继续使用其新属性值或原始属性值登录。有关更多信息，请参阅 [当用户更改其电子邮件或电话号码时应进行验证](signing-up-users-in-your-app.md#verifying-when-users-change-their-email-or-phone-number)。
1. **必填属性**显示用户注册或您创建用户之前必须为其提供值的属性。只能在创建用户池时设置必需属性。
1. **自定义属性**对用户创建和注册过程很重要，因为只有在首次创建用户时才能为*不可变的*自定义属性设置值。有关自定义属性的更多信息，请参阅[自定义属性](user-pool-settings-attributes.md#user-pool-settings-custom-attributes)。
1. 如果您希望用户能够使用[未经身份验证的](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html#user-pool-apis-auth-unauth) `SignUp` API 生成新账户，请在**自助注册**中选择**启用自行注册**。如果您禁用自助注册，则只能在 Amazon Cognito 控制台中或通过 API 请求[AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html)以管理员身份创建新用户。在自助注册处于非活动状态的用户池中，[SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html)API 请求会返回`NotAuthorizedException`，托管登录不会显示**注册**链接。
对于您计划以管理员身份创建用户的用户池，可以在**身份验证方法**菜单中**管理员设置的临时密码到期时间**下的设置中配置临时密码的持续时间。
以管理员身份创建用户的另一个重要元素是邀请消息。创建新用户时，Amazon Cognito 会给他们发送一条包含您的应用程序链接的消息，以便他们可以首次登录。可以在**身份验证方法**菜单中的**消息模板**下自定义这个消息模板。
您可以使用客户端密钥配置[机密应用程序客户端](user-pool-settings-client-apps.md#user-pool-settings-client-app-client-types.title)（通常是 Web 应用程序），以防止在没有应用程序客户端密钥的情况下注册。作为安全最佳实践，请勿在公共应用程序客户端（通常是移动应用程序）中分发应用程序客户端密钥。您可以在 Amazon Cognito 控制台的**应用程序客户端**菜单中使用客户端密钥创建应用程序客户端。
------
#### [ Amazon Cognito user pools API ]
您可以通过编程方式在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)或 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)API 请求中设置用于在用户池中创建用户的参数。
该[AdminCreateUserConfig](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-AdminCreateUserConfig)元素为用户池的以下属性设置值。
1. 启用自助注册
1. 向管理员创建的新用户发送的邀请消息
如果将以下示例添加到完整的 API 请求正文中，可设置一个用户池（自助注册为非活动状态）和一封基本的邀请电子邮件。
```
"AdminCreateUserConfig": {
"AllowAdminCreateUserOnly": true,
"InviteMessageTemplate": {
"EmailMessage": "Your username is {username} and temporary password is {####}.",
"EmailSubject": "Welcome to ExampleApp",
"SMSMessage": "Your username is {username} and temporary password is {####}."
}
}
```
[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)或 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)API 请求的以下附加参数控制新用户的创建。
[AutoVerifiedAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-AutoVerifiedAttributes)
注册新用户时要[自动向其发送消息的](user-pool-settings-email-phone-verification.md#user-pool-settings-email-phone-verification.title)属性、电子邮件地址或电话号码。
[策略](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Policies)
用户池[密码策略](managing-users-passwords.md#user-pool-settings-policies.title)。
[架构](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Schema)
用户池[自定义属性](user-pool-settings-attributes.md#user-pool-settings-custom-attributes.title)。它们对用户的创建和注册过程很重要，因为只有在首次创建用户时才能为*不可变的*自定义属性设置值。
此参数还将为您的用户池设置必填属性。如果将以下文本插入到完整 API 请求正文的 `Schema` 元素中，将把 `email` 属性设为必填属性。
```
{
"Name": "email",
"Required": true
}
```
------
# 注册并确认用户账户
可通过以下任一方法将用户账户添加到您的用户池中：
+ 用户在您用户池的客户端应用程序中进行注册。这可以是移动应用程序或 Web 应用程序。
+ 您可以将用户账户导入到用户池中。有关更多信息，请参阅 [通过 CSV 文件将用户导入用户池中](cognito-user-pools-using-import-tool.md)。
+ 您可以在用户池中创建用户账户并邀请用户登录。有关更多信息，请参阅 [以管理员身份创建用户账户](how-to-create-user-accounts.md)。
自行注册的用户必须得到确认才可登录。导入和创建的用户已经过确认，但他们必须在首次登录时创建自己的密码。以下部分将介绍确认过程以及电子邮件和电话验证。
**注册时的密码**
Amazon Cognito 要求所有用户在注册时提供密码，但以下情况除外。如果满足*所有*这些条件，则可以在注册操作中忽略密码。
1. [无密码登录](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)在您的用户池和应用程序客户端中处于活动状态。
1. 您的应用程序是使用 AWS SDK 中的身份验证模块定制的。托管登录和托管 UI 始终要求提供密码。
1. 用户为您允许的无密码登录方法（电子邮件或短信一次性密码 ()OTPs）提供属性值。例如，如果您允许使用电子邮件和电话 OTP 登录，则用户可以提供电话号码或电子邮件地址，但是如果您只允许使用电子邮件登录，则他们必须提供电子邮件地址。
1. 您的用户池会[自动验证](#allowing-users-to-sign-up-and-confirm-themselves)用户可在无密码登录中使用的属性。
1. 对于任何给定的[SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html)请求，用户都不会为 P [asswor](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Password) d 参数提供值。
## 用户账户确认概览
下图阐明了确认过程：
![\[当用户输入确认代码时，将自动验证电子邮件或电话。\]](http://docs.aws.amazon.com/zh_cn/cognito/latest/developerguide/images/amazon-cognito-sign-in-confirm-user.png)
用户账户可以处于以下任一状态：
**已注册（未确认）**
用户已成功注册，但在用户账户得到确认之前无法登录。在此状态下，用户已启用，但未得到确认。
自行注册的新用户由此状态开始。
**已确认**
用户账户已确认，用户可以登录。当用户输入代码或点击电子邮件链接以确认其用户账户时，系统将自动验证电子邮件或电话号码。代码或链接的有效期为 24 小时。
如果管理员或预注册 Lambda 触发器确认了用户账户，则可能没有与该账户关联的经验证的电子邮件或电话号码。
**需要重置密码**
用户账户已确认，但用户必须请求代码并重置其密码，然后才可以登录。
由管理员或开发人员导入的用户账户以此状态开始。
**强制更改密码**
用户账户已确认，用户可以使用临时密码进行登录。但在首次登录时，用户必须将其密码更改为新值，然后才能执行任何其他操作。
由管理员或开发人员创建的用户账户以此状态开始。
**已禁用**
在可以删除用户账户之前，必须禁用该用户的登录访问权限。
**更多资源**
+ [使用 Amazon Cognito 检测和修复不活跃的用户账户](https://aws.amazon.com/blogs/security/detecting-and-remediating-inactive-user-accounts-with-amazon-cognito/)
## 在注册时验证联系人信息
当新用户注册您的应用程序时，您可能希望他们提供至少一种联系方式。例如，利用用户的联系人信息，您可以：
+ 在用户选择重置其密码时发送临时密码。
+ 在更新用户的个人信息或财务信息后向用户发送通知。
+ 发送促销信息（例如，特别优惠或折扣）。
+ 发送账户摘要或账单提醒。
对于像这样的使用案例，将消息发送到经过验证的目的地非常重要。否则，您可能会将消息发送到错误键入的无效电子邮件地址或电话号码。或者更糟糕的是，您可能会将敏感信息发送给冒充您的用户的坏人。
为了帮助确保您仅将消息发送给正确的人员，请配置您的 Amazon Cognito 用户池以使用户在注册时必须提供以下内容：
1. 一个电子邮件地址或电话号码。
1. Amazon Cognito 发送到该电子邮件地址或电话号码的验证码。如果 24 小时过去并且您的用户的代码或链接不再有效，请调用 [ResendConfirmationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html)API 操作生成并发送新的代码或链接。
通过提供验证码，用户可以证明他们有权访问收到该代码的邮箱或手机。在用户提供该代码后，Amazon Cognito 将通过以下方式更新用户池中的用户相关信息：
+ 将用户的状态设置为 `CONFIRMED`。
+ 更新用户的属性以指示已验证电子邮件地址或电话号码。
要查看此信息，您可以使用 Amazon Cognito 控制台。或者，您可以使用 `AdminGetUser` API 操作、带的`admin-get-user` AWS CLI命令或其中一个中的相应操作 AWS SDKs。
如果用户具有经验证的联系方式，Amazon Cognito 会在用户请求重置密码时自动向其发送消息。
### 确认和验证用户属性的其他操作
以下用户活动会验证用户属性。您无需将这些属性设置为自动验证：列出的操作在所有情况下都会将其标记为已验证。
**电子邮件地址**
1. 使用电子邮件一次性密码（OTP）成功完成[无密码身份验证](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)。
1. 使用电子邮件 OTP 成功完成[多重身份验证（MFA）](user-pool-settings-mfa.md)。
**Phone number（电话号码）**
1. 使用短信 OTP 成功完成[无密码身份验证](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)。
1. 使用短信 OTP 成功完成 [MFA](user-pool-settings-mfa.md)。
### 配置您的用户池以要求电子邮件或手机验证
验证用户的电子邮件地址和电话号码时，确保可以联系到用户。完成中的以下步骤， AWS 管理控制台 将您的用户池配置为要求您的用户确认其电子邮件地址或电话号码。
**注意**
如果您的账户中还没有用户池，请参阅[用户池入门](getting-started-user-pools.md)。
**配置用户池**
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 从导航窗格中选择**用户池**。从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**登录**菜单，然后找到**属性验证和用户账户确认**。选择**编辑**。
1. 在 **Cognito 辅助验证和确认**下，选择是否**允许 Cognito 自动发送消息以进行验证和确认**。启用此设置后，当用户注册或您创建用户配置文件时，Amazon Cognito 会向您选择的用户联系人属性发送消息。为验证属性并确认登录的用户配置文件，Amazon Cognito 会通过消息向用户发送代码或链接。用户随后必须在您的 UI 中输入相应代码，这样，您的应用才能在 `ConfirmSignUp` 或 `AdminConfirmSignUp` API 请求中对其进行确认。
**注意**
您还可以禁用 **Cognito 辅助验证和确认**并使用经过身份验证的 API 操作或 Lambda 触发器验证属性并确认用户。
如果您选择此选项，则 Amazon Cognito 不会在用户注册时发送验证码。如果您要使用自定义身份验证流程验证至少一种联系方式，而不使用来自 Amazon Cognito 的验证码，请选择此选项。例如，您可以使用一个预注册 Lambda 触发器，该触发器将自动验证属于特定域的电子邮件地址。
如果您不验证用户的联系人信息，用户可能无法使用您的应用程序。请记住，用户需要经验证的联系人信息才能：
**重置密码** – 当用户在您的应用程序中选择调用 `ForgotPassword` API 操作的选项时，Amazon Cognito 会将临时密码发送到用户的电子邮件地址或电话号码。Amazon Cognito 仅在用户具有至少一个经验证的联系方式时发送此密码。
**通过使用电子邮箱地址或电话号码作为别名进行登录** – 如果您将用户池配置为允许这些别名，则用户只能在别名经过验证后使用别名进行登录。有关更多信息，请参阅 [自定义登录属性](user-pool-settings-attributes.md#user-pool-settings-aliases)。
1. 选择您的**要验证的属性**：
**发送 SMS 消息，验证电话号码**
Amazon Cognito 将在用户注册时通过 SMS 消息发送验证码。如果您通常通过 SMS 消息与用户通信，请选择此选项。例如，如果您要发送交付通知、约会确认或提醒，则将需要使用经过验证的电话号码。确认账户时，用户电话号码将成为已验证属性；您必须采取其它操作来验证用户电子邮件地址并与其进行通信。
**发送电子邮件消息，验证电子邮件地址**
Amazon Cognito 将在用户注册时通过电子邮件发送验证码。如果您通常通过电子邮件与用户通信，请选择此选项。例如，如果您要发送账单、订单摘要或特别优惠，则将需要使用经过验证的电子邮件地址。确认账户时，用户电子邮件地址将成为已验证属性；您必须采取其它操作来验证用户电话号码并与其进行通信。
**如果电话号码可用，则发送 SMS 消息，否则发送电子邮件**
如果您不要求所有用户都拥有相同的经验证的联系方式，请选择此选项。在这种情况下，您的应用程序中的注册页面可能会要求用户仅验证其首选联系方式。当 Amazon Cognito 发送验证码时，会将该代码发送到来自您应用程序的 `SignUp` 请求中提供的联系方式。如果用户同时提供了电子邮件地址和电话号码，并且您的应用程序在 `SignUp` 请求中提供了这两种联系方式，Amazon Cognito 将仅向电话号码发送验证码。
如果您要求用户同时验证电子邮件地址和电话号码，则选择此选项。Amazon Cognito 将在用户注册时验证一种联系方式，而且您的应用程序必须在用户登录后验证另一种联系方式。有关更多信息，请参阅 [在您要求用户确认电子邮件地址和电话号码的情况下](#verification-email-plus-phone)。
1. 选择**保存更改**。
### 使用电子邮件或电话验证的身份验证流程
如果您的用户池要求用户验证其联系人信息，则当用户注册时，您的应用程序必须促进以下流程：
1. 用户通过输入用户名、电话号码、 and/or 电子邮件地址以及可能的其他属性来注册您的应用程序。
1. Amazon Cognito 服务接收来自应用程序的注册请求。验证该请求包含注册所需的所有属性后，该服务将完成注册过程并向用户的手机（通过 SMS 消息）或电子邮件发送确认码。代码的有效期为 24 小时。
1. 该服务向应用程序返回信息，表示注册过程已完成且用户账户正等待确认。响应中包含关于确认代码所发送到位置的信息。此时，用户账户处于未确认状态，而且用户的电子邮件地址和电话号码未经验证。
1. 现在，应用程序会提示用户输入确认代码。用户无需立即输入代码。但是，用户只有在输入确认代码后才可登录。
1. 用户在应用程序中输入确认代码。
1. 应用程序调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html) 将代码发送到 Amazon Cognito 服务，该服务将验证代码并在代码正确时将用户账户设置为已确认状态。成功确认用户账户之后，Amazon Cognito 服务会自动将用于确认（电子邮件地址或电话号码）的属性标记为已验证。除非此属性的值发生更改，否则用户无需再次进行验证。
1. 此时，用户账户处于已确认状态，用户可以登录。
### 在您要求用户确认电子邮件地址和电话号码的情况下
Amazon Cognito 在用户注册时仅验证一种联系方式。如果 Amazon Cognito 必须在验证电子邮件地址或电话号码之间进行选择，则会选择通过 SMS 消息发送验证码来验证电话号码。例如，如果您将用户池配置为允许用户验证电子邮件地址或电话号码，并且您的应用程序在注册时提供了这两个属性，则 Amazon Cognito 将仅验证电话号码。在用户验证其电话号码后，Amazon Cognito 会将用户的状态设置为 `CONFIRMED`，并允许用户登录您的应用程序。
在用户登录后，您的应用程序会提供相应选项来验证在注册期间未验证的联系方式。为了验证第二种联系方式，您的应用程序将调用 `VerifyUserAttribute` API 操作。请注意，此操作需要 `AccessToken` 参数，而 Amazon Cognito 只为经过身份验证的用户提供访问令牌。因此，您只能在用户登录后验证第二种联系方式。
如果您要求用户同时验证电子邮件地址和电话号码，请执行以下操作：
1. 配置用户池以允许用户验证电子邮件地址或电话号码。
1. 在应用程序的注册流程中，要求用户提供电子邮件地址和电话号码。调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html) API 操作，并为 `UserAttributes` 参数提供电子邮件地址和电话号码。此时，Amazon Cognito 会向用户的手机发送一个验证码。
1. 在应用程序界面中，会显示一个确认页面以供用户输入验证码。通过调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html) API 操作来确认用户。此时，用户的状态为 `CONFIRMED`，并且用户的电话号码已验证，但电子邮件地址未验证。
1. 显示登录页，并通过调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 操作对用户进行身份验证。对用户进行身份验证后，Amazon Cognito 将向您的应用程序返回访问令牌。
1. 调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html) API 操作。在请求中指定以下参数：
+ `AccessToken` – Amazon Cognito 在用户登录时返回的访问令牌。
+ `AttributeName` – 将 `"email"` 指定为属性值。
Amazon Cognito 将向用户的电子邮件地址发送一个验证码。
1. 显示一个确认页面以供用户输入验证码。当用户提交代码时，请调用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) API 操作。在请求中指定以下参数：
+ `AccessToken` – Amazon Cognito 在用户登录时返回的访问令牌。
+ `AttributeName` – 将 `"email"` 指定为属性值。
+ `Code` – 用户提供的验证码。
此时，电子邮件地址已验证。
## 允许用户在您的应用程序中注册但以用户池管理员身份进行确认
您可能不希望您的用户池自动在用户池中发送验证消息，但仍希望允许任何人注册账户。例如，该模型为人工审查新的注册请求以及批量验证和处理注册留出了空间。您可以在 Amazon Cognito 控制台中或通过 IAM 身份验证的 API 操作确认新的用户账户。[AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html)无论您的用户池是否发送验证消息，您都能以管理员身份确认用户账户。
您只能使用此方法确认用户的自助注册。要确认您以管理员身份创建的用户，请创建`Permanent`设置为[AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html)的 API 请求`True`。
1. 用户通过输入用户名、电话号码、 and/or 电子邮件地址以及可能的其他属性来注册您的应用程序。
1. Amazon Cognito 服务接收来自应用程序的注册请求。验证该请求包含注册所需的所有属性之后，该服务将完成注册过程，并向应用程序返回信息，表示注册已完成且正在等待确认。此时，用户账户处于未确认状态。账户经过确认后，用户才可登录。
1. 确认用户的账户。您必须使用 AWS 凭据登录 AWS 管理控制台 或签署 API 请求才能确认账户。
1. 要在 Amazon Cognito 控制台中确认用户，请导航到**用户**菜单，选择要确认的用户，然后从**操作**菜单中选择**确认**。
1. 要在 AWS API 或 CLI 中确认用户，请创建 [AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html)API 请求，或者[admin-confirm-sign-up](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-confirm-sign-up.html)在 AWS CLI。
1. 此时，用户账户处于已确认状态，用户可以登录。
## 计算密钥哈希值
作为最佳实践，请将客户端密钥分配给您的机密应用程序客户端。当您向应用程序客户端分配客户端密钥时，您的 Amazon Cognito 用户池 API 请求必须包括一个哈希值，用于包含请求正文中的客户端密钥。为了验证您对以下列表中 API 操作的客户端密钥的了解，请将客户端密钥与应用程序客户端 ID 和用户的用户名连接起来，然后对该字符串进行 base64 编码。
应用程序将用户登录到具有密钥哈希值的客户端时，您可以使用任何用户池登录属性的值作为密钥哈希值的用户名元素。应用程序在使用 `REFRESH_TOKEN_AUTH` 的身份验证操作中请求新令牌时，用户名元素的值取决于您的登录属性。如果您的用户池没有将 `username` 用作登录属性，请通过用户的访问令牌或 ID 令牌中的 `sub` 声明设置密钥哈希用户名值。如果 `username` 为登录属性，请通过 `username` 声明设置密钥哈希用户名值。
以下 Amazon Cognito 用户池 APIs 接受参数中的客户端密钥哈希值。`SecretHash`
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmSignUp.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html)
+ [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html)
此外，以下内容 APIs 接受`SECRET_HASH`参数中的客户端密钥哈希值，无论是在身份验证参数中还是在质询响应中。
| API 操作 | SECRET\$1HASH 的父参数 |
| --- |--- |
| InitiateAuth | AuthParameters |
| AdminInitiateAuth | AuthParameters |
| RespondToAuthChallenge | ChallengeResponses |
| AdminRespondToAuthChallenge | ChallengeResponses |
密钥哈希值是 Base 64 编码的加密哈希消息身份验证代码（HMAC，Hash Message Authentication Code），使用用户池客户端的私有密钥、用户名以及消息中的客户端 ID 进行计算。以下伪代码显示如何计算此值。在此伪代码中，`+`表示串联，表示使用 Hmac 生成 HMAC 值的函数，并`HMAC_SHA256``Base64`表示生成 Base-64 编码SHA256版本的哈希输出的函数。
```
Base64 ( HMAC_SHA256 ( "Client Secret Key", "Username" + "Client Id" ) )
```
有关如何计算和使用`SecretHash`参数的详细概述，请参阅[如何解决我的 Amazon Cognito 用户池 API 中的 “无法验证客户端的秘密哈希” 错误？](https://aws.amazon.com/premiumsupport/knowledge-center/cognito-unable-to-verify-secret-hash/) 在 AWS 知识中心中。
您可以在服务器端应用程序代码中使用以下代码示例：
------
#### [ Shell ]
```
echo -n "[username][app client ID]" | openssl dgst -sha256 -hmac [app client secret] -binary | openssl enc -base64
```
------
#### [ Java ]
```
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public static String calculateSecretHash(String userPoolClientId, String userPoolClientSecret, String userName) {
final String HMAC_SHA256_ALGORITHM = "HmacSHA256";
SecretKeySpec signingKey = new SecretKeySpec(
userPoolClientSecret.getBytes(StandardCharsets.UTF_8),
HMAC_SHA256_ALGORITHM);
try {
Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);
mac.init(signingKey);
mac.update(userName.getBytes(StandardCharsets.UTF_8));
byte[] rawHmac = mac.doFinal(userPoolClientId.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(rawHmac);
} catch (Exception e) {
throw new RuntimeException("Error while calculating ");
}
}
```
------
#### [ Python ]
```
import sys
import hmac, hashlib, base64
username = sys.argv[1]
app_client_id = sys.argv[2]
key = sys.argv[3]
message = bytes(sys.argv[1]+sys.argv[2],'utf-8')
key = bytes(sys.argv[3],'utf-8')
secret_hash = base64.b64encode(hmac.new(key, message, digestmod=hashlib.sha256).digest()).decode()
print("SECRET HASH:",secret_hash)
```
------
## 无需验证电子邮件或电话号码即可确认用户账户
预注册 Lambda 触发器可用于在注册时自动确认用户账户，而无需提供确认码或者验证电子邮件或电话号码。通过此方法进行确认的用户可立即登录，而无需接收代码。
您还可通过此触发器将用户的电子邮件或电话号码标记为已验证。
**注意**
虽然这种方法对刚入门的用户而言很方便，但建议至少自动验证电子邮件或电话号码之一。否则，如果用户忘记密码，可能就无法进行恢复。
如果您不要求用户在注册时接收并输入确认码，也不在预注册 Lambda 触发器中自动验证电子邮件和电话号码，则您将承担对于该用户账户不具备经验证的电子邮件地址或电话号码的风险。用户可以稍后验证电子邮件地址或电话号码。但是，如果用户忘记自己的密码且没有经验证的电子邮件地址或电话号码，则用户将被锁定而无法使用账户，因为忘记密码流程需要经验证的电子邮件或电话号码以便向用户发送验证码。
## 当用户更改其电子邮件或电话号码时应进行验证
在您配置了多个登录名的用户池中，用户可以在登录时输入电话号码或电子邮件地址作为用户名。当用户在应用程序中更新其电子邮件地址或电话号码时，Amazon Cognito 会立即向他们发送带有验证码的消息，用于验证其对新属性值的所有权。要启用自动发送这些验证码，请参阅[配置电子邮件或电话验证](user-pool-settings-email-phone-verification.md)。
收到验证码的用户必须在请求中将该验证码提供给 Amazon Cognito。[VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html)提供验证码后，他们的属性将被标记为已验证。通常，当用户更新其电子邮件地址或电话号码时，您需要先验证他们是否拥有这个新值，然后他们才能使用新值登录和接收消息。用户池有一个可配置的选项，用于确定用户是否必须验证其电子邮件地址或电话号码的更新信息。
此选项是用户池属性 `AttributesRequireVerificationBeforeUpdate`。在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-UserAttributeUpdateSettings)或[UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-UserAttributeUpdateSettings)请求中对其进行配置，或者在 Amazon Cognito 控制台**的 “**注册**” 菜单中使用待更新时保持原始属性值处于活动状态**设置。
您的用户池如何处理电子邮件地址和电话号码的更新与用户池的用户名配置有关。用户池用户名可以位于*用户名属性*配置中，其中登录名为电子邮件地址、电话号码或两者兼而有之。它们也可以位于*别名属性*配置中，其中 `username` 属性是登录名，电子邮件地址、电话号码或首选用户名作为备用登录名。有关更多信息，请参阅[自定义登录属性](user-pool-settings-attributes.md#user-pool-settings-aliases)。
您也可以使用自定义消息 Lambda 触发器来自定义验证消息。有关更多信息，请参阅 [自定义消息 Lambda 触发器](user-pool-lambda-custom-message.md)。当用户的电子邮件地址或电话号码未经验证时，您的应用程序应通知用户必须验证该属性，并为用户提供一个按钮或链接来输入其验证码。
下表描述了当用户更改其登录属性的值时，`AttributesRequireVerificationBeforeUpdate` 和别名设置如何确定结果。
| 用户名配置 | 用户必须验证新属性时的行为 | 用户不需要验证新属性时的行为 |
| --- | --- | --- |
| 用户名属性 | 原始属性仍处于已验证状态，有资格登录，且为原始值。当用户验证新值时，Amazon Cognito 会更新属性值，将其标记为已验证，并使其符合登录资格。 | Amazon Cognito 将属性更新为新值。新值具有登录资格。当用户验证新值时，Amazon Cognito 会将其标记为已验证。 |
| 别名属性 | 原始属性仍处于已验证状态，有资格登录，且为原始值。当用户验证新值时，Amazon Cognito 会更新属性值，将其标记为已验证，并使其符合登录资格。 | Amazon Cognito 将属性更新为新值。原始属性值或新属性值均无登录资格。当用户验证新值时，Amazon Cognito 会更新属性值，将其标记为已验证，并使其符合登录资格。 |
**示例 1**
用户 1 使用电子邮件地址 `user1@example.com` 登录您的应用程序，用户名为 `user1`（别名属性）。您的用户池配置为验证登录属性的更新并自动发送验证消息。他们请求将其电子邮件地址更新为 `user1+foo@example.com`。他们通过 `user1+foo@example.com` 接收验证电子邮件，并且只能使用电子邮件地址 `user1@example.com` *重新登录*。之后，他们输入验证码，并且只能使用电子邮件地址 `user1+foo@example.com` 重新登录。
**示例 2**
用户 2 使用电子邮件地址 `user2@example.com` 登录您的应用程序，并提供用户名（别名属性）。您的用户池配置为*不*验证登录属性的更新并自动发送验证消息。他们请求将其电子邮件地址更新为 `user2+bar@example.com`。他们通过 `user2+bar@example.com` 接收验证电子邮件，并且*无法重新登录*。之后，他们输入验证码，并且只能使用电子邮件地址 `user2+bar@example.com` 重新登录。
**示例 3**
用户 3 使用电子邮件地址 `user3@example.com` 登录您的应用程序，没有提供用户名（用户名属性）。您的用户池配置为*不*验证登录属性的更新并自动发送验证消息。他们请求将其电子邮件地址更新为 `user3+baz@example.com`。他们通过 `user3+baz@example.com` 接收验证电子邮件，但是他们*可以立即登录*，无需使用验证码执行任何其他操作。
## 针对由管理员或开发人员创建的用户账户的确认和验证过程
由管理员或开发人员创建的用户账户已经处于已确认状态，所以用户无需输入确认代码。Amazon Cognito 服务向这些用户发送的邀请消息包含用户名和临时密码。用户需要在登录前更改密码。有关更多信息，请参阅[自定义电子邮件和 SMS 消息](how-to-create-user-accounts.md#creating-a-new-user-customize-messages)中的 [以管理员身份创建用户账户](how-to-create-user-accounts.md)和[使用 Lambda 触发器自定义用户池工作流](cognito-user-pools-working-with-lambda-triggers.md)中的自定义消息触发器。
## 针对导入的用户账户的确认和验证过程
使用 AWS 管理控制台、CLI 或 API 中的用户导入功能（参见[通过 CSV 文件将用户导入用户池中](cognito-user-pools-using-import-tool.md)）创建的用户账户已处于已确认状态，因此用户无需输入确认码。没有发送邀请消息。但是，导入的用户账户要求用户首先调用 `ForgotPassword` API 来请求代码，然后通过调用 `ConfirmForgotPassword` API 来使用发送的代码创建密码，之后方可登录。有关更多信息，请参阅 [要求导入的用户重置密码](cognito-user-pools-using-import-tool.md#cognito-user-pools-using-import-tool-password-reset)。
导入用户账户时，用户的电子邮件或电话号码必须已标记为已验证，从而用户无需验证即可登录。
## 在测试应用程序时发送电子邮件
当用户在您的用户池的客户端应用程序中创建和管理其账户时，Amazon Cognito 将向用户发送电子邮件。如果您将用户池配置为要求电子邮件验证，Amazon Cognito 将在以下情况下发送电子邮件：
+ 用户注册。
+ 用户更新其电子邮件地址。
+ 用户执行一项调用 `ForgotPassword` API 操作的操作。
+ 您以管理员身份创建用户账户。
根据发起电子邮件递送的操作，电子邮件将包含验证码或临时密码。您的用户必须接收这些电子邮件并理解消息。否则，他们可能无法登录并使用您的应用程序。
要确保电子邮件成功发送并且邮件看起来正确，请测试应用程序中从 Amazon Cognito 启动电子邮件传送的操作。例如，通过使用应用程序中的注册页面或通过使用 `SignUp` API 操作，您可以通过使用测试电子邮件地址进行注册来启动电子邮件传送。在通过此方式进行测试时，请记住以下几点：
**重要提示**
当您使用电子邮件地址测试从 Amazon Cognito 启动电子邮件传送的操作时，请勿使用虚假的电子邮件地址（没有邮箱的电子邮件地址）。使用真实的电子邮件地址才能接收来自 Amazon Cognito 的电子邮件，而不会创建*查无此人的邮件*。
在 Amazon Cognito 未能将电子邮件传送到收件人邮箱时会产生查无此人的邮件，如果邮箱不存在，则始终会发生这种情况。
Amazon Cognito 限制了持续出现硬退邮件的 AWS 账户可以发送的电子邮件数量。
当您测试启动电子邮件传送的操作时，请使用下列电子邮件地址之一以防止出现查无此人的邮件：
+ 您拥有的用于测试的电子邮件账户的地址。当您使用自己的电子邮件地址时，您将收到 Amazon Cognito 发送的电子邮件。利用此电子邮件，您可以使用验证码来测试应用程序中的注册体验。如果您为用户池自定义了电子邮件，则可检查自定义项看起来是否正确。
+ 邮箱模拟器地址：*success@simulator.amazonses.com*。如果您使用模拟器地址，Amazon Cognito 将成功发送电子邮件，但您无法查看。当您不需要使用验证码并且不需要检查电子邮件时，此选项很有用。
+ 添加了任意标签的邮箱模拟器地址（如 *success\$1user1@simulator.amazonses.com* 或 *success\$1user2@simulator.amazonses.com*）。Amazon Cognito 可成功向这些地址发送电子邮件，但您无法查看其发送的电子邮件。当您希望通过向用户池添加多个测试用户来测试注册过程，并且每个测试用户都具有一个唯一的电子邮件地址时，此选项很有用。
# 配置电子邮件或电话验证
您可以在**身份验证方法**菜单下选择电子邮件或电话验证的设置。有关多重验证 (MFA) 的详细信息，请参阅[SMS 文本消息 MFA](user-pool-settings-mfa-sms-email-message.md)。
Amazon Cognito 使用 Amazon SNS 发送 SMS 消息。如果您 AWS 服务 之前没有发送过来自亚马逊 Cognito 或其他任何公司的短信，Amazon SNS 可能会将您的账户置于短信沙箱中。建议您在将账户从沙盒移到生产环境之前，向已验证的电话号码发送测试消息。此外，如果您计划向美国的目标电话号码发送短信，则必须从 Amazon Pinpoint 获取源 ID 或发件人 ID。要为 Amazon Cognito 用户池配置 SMS 消息，请参阅 [Amazon Cognito 用户池的短信设置](user-pool-sms-settings.md)。
Amazon Cognito 可以自动验证电子邮件地址或电话号码。要进行此验证，Amazon Cognito 将发送验证码或验证链接。对于电子邮件地址，Amazon Cognito 可以通过电子邮件发送代码或链接。当您在 Amazon Cognito 控制台的**消息模板**菜单中编辑**验证消息**模板时，您可以选择**验证类型**，即**代码**或**链接**。有关更多信息，请参阅 [自定义电子邮件验证消息](cognito-user-pool-settings-message-customizations.md#cognito-user-pool-settings-email-verification-message-customization)。
对于电话号码，Amazon Cognito 以 SMS 文本消息的形式发送代码。
Amazon Cognito 必须验证电话号码或电子邮件地址来确认用户，帮助他们恢复忘记的密码。或者，您可以使用注册前 Lambda 触发器或使用 API 操作自动确认用户[AdminConfirmSignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminConfirmSignUp.html)。有关更多信息，请参阅 [注册并确认用户账户](signing-up-users-in-your-app.md)。
验证代码或链接的有效期为 24 小时。
如果您选择要求通过电子邮件地址或电话号码进行验证，则在用户注册时，Amazon Cognito 将自动发送验证代码或链接。如果用户池已配置了 [自定义 SMS 发件人 Lambda 触发器](user-pool-lambda-custom-sms-sender.md) 或 [自定义电子邮件发件人 Lambda 触发器](user-pool-lambda-custom-email-sender.md)，则会改为调用该函数。
**注意**
Amazon SNS 会另外收取用于验证电话号码的 SMS 文本消息费用。发送电子邮件不收费。有关 Amazon SNS 定价的信息，请参阅 [Worldwide SMS 定价](https://aws.amazon.com/sns/sms-pricing/)。有关提供 SMS 消息收发服务的最新国家/地区列表，请参阅[支持的区域和国家/地区](https://docs.aws.amazon.com/sns/latest/dg/sms_supported-countries.html)。
当您在应用程序中测试从 Amazon Cognito 生成电子邮件的操作时，请使用 Amazon Cognito 可以发送到而不会查无此人的邮件的真实电子邮件地址。有关更多信息，请参阅 [在测试应用程序时发送电子邮件](signing-up-users-in-your-app.md#managing-users-accounts-email-testing)。
忘记密码流程要求通过用户的电子邮件或电话号码来验证用户。
**重要**
如果用户同时注册了电话号码和电子邮件地址，并且用户池设置需要验证这两个属性，那么 Amazon Cognito 会通过 SMS 消息将验证码发送到电话号码上。Amazon Cognito 尚未验证电子邮件地址，因此您的应用程序必须致电[GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html)以查看电子邮件地址是否在等待验证。如果确实需要验证，则应用程序必须致电[GetUserAttributeVerificationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUserAttributeVerificationCode.html)以启动电子邮件验证流程。然后它必须通过致电提交验证码[VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html)。
您可以调整 AWS 账户 和单条消息的短信支出配额。该限额仅适用于发送 SMS 消息的费用。有关更多信息，请参阅**什么是账户级和消息级支出配额及其运作方式？** 在 [Amazon SNS FAQs](https://aws.amazon.com/sns/faqs/) 中。
Amazon Cognito 使用您创建用户池的地方或下表中传统的 Amazon SNS **备用区域的 Amazon SNS** 资源发送短信。 AWS 区域 亚太地区（首尔）区域中的 Amazon Cognito 用户池例外。这些用户池使用您在亚太地区（东京）区域中的 Amazon SNS 配置。有关更多信息，请参阅 [选择 S AWS 区域 MS 消息](user-pool-sms-settings.md#sms-choose-a-region)。
| Amazon Cognito 区域 | 旧版 Amazon SNS 备用区域 |
| --- | --- |
| 美国东部（俄亥俄州） | 美国东部（弗吉尼亚州北部） |
| 亚太地区（孟买） | 亚太地区（新加坡） |
| 亚太地区（首尔） | 亚太地区（东京） |
| 加拿大（中部） | 美国东部（弗吉尼亚州北部） |
| 欧洲地区（法兰克福） | 欧洲地区（爱尔兰） |
| 欧洲地区（伦敦） | 欧洲地区（爱尔兰） |
**示例：**如果您的 Amazon Cognito 用户池位于亚太地区（孟买）区域，并且您增加了在 ap-southeast-1 区域中的支出限额，则可能不希望请求单独增加 ap-south-1 的支出限额。而是可以使用亚太地区（新加坡）中的 Amazon SNS 资源。
## 验证对于电子邮件地址和电话号码的更新
在用户更改电子邮件地址或电话号码属性的值后，这些属性可以立即变为活动但未经验证的状态。Amazon Cognito 还可以要求您的用户在 Amazon Cognito 更新属性之前验证新值。当您要求用户首先验证新值时，他们可以使用原始值进行登录和接收消息，直到他们验证新值。
当您的用户可以使用其电子邮件地址或电话号码作为用户池中的登录别名时，他们的已更新属性的登录名取决于您是否要求验证已更新的属性。当您要求用户验证已更新的属性时，用户可以使用原始属性值登录，直到他们验证新值。如果您不要求用户验证已更新的属性，则在验证新值之前，用户无法使用新属性值或原始属性值登录或接收消息。
例如，您的用户池允许使用电子邮件地址别名登录，并要求用户在更新时验证其电子邮件地址。Sue 以 `sue@example.com` 身份登录，想将她的电子邮件地址更改为 `sue2@example.com`，但是不小心输入了 `ssue2@example.com`。Sue 没有收到验证电子邮件，所以她无法验证 `ssue2@example.com`。Sue 以 `sue@example.com` 身份登录，然后在您的应用程序中重新提交表单，以将她的电子邮件地址更新为 `sue2@example.com`。她收到此电子邮件，向您的应用程序提供验证码，然后开始以 `sue2@example.com` 身份登录。
**当用户更新属性并且您的用户池验证新的属性值时**
+ 在确认代码以验证新值之前，用户可以使用原始属性值登录。
+ 用户只有在确认代码以验证新值后，才能使用新属性值登录。
+ 如果您在 [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)API 请求`true`中`phone_number_verified`将`email_verified`或设置为，则他们可以在确认 Amazon Cognito 发送给他们的代码之前登录。
**当用户更新属性而您的用户池未验证新的属性值时**
+ 用户无法使用原始属性值登录或接收消息。
+ 在确认代码以验证新属性值之前，用户无法使用新属性值登录或接收除确认码之外的消息。
+ 如果您在 [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)API 请求`true`中`phone_number_verified`将`email_verified`或设置为，则他们可以在确认 Amazon Cognito 发送给他们的代码之前登录。
## 当用户更新其电子邮件地址或电话号码时，需要进行属性验证
1. 登录 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 在导航窗格中，选择 **用户池**，然后选择要编辑的用户池。
1. 在**注册**菜单中，在**属性验证和用户账户确认**下选择**编辑**。
1. 选择 **Keep original attribute value active when an update is pending**（等待更新时，保持原始属性值处于活动状态）。
1. 在 **Active attribute values when an update is pending**（等待更新时的活动属性值）下，选择您希望在 Amazon Cognito 更新值之前要求用户验证的属性。
1. 选择**保存更改**。
要要求使用 Amazon Cognito API 进行属性更新验证，您可以在请求中设置`AttributesRequireVerificationBeforeUpdate`参数。[UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)
## 授权 Amazon Cognito 代表您发送消息。
要代表您向您的用户发送短信，Amazon Cognito 需要具有您的权限。要授予该权限，您可以创建一个 AWS Identity and Access Management (IAM) 角色。在 Amazon Cognito 控制台的**身份验证方法**菜单的“SMS”下，选择**编辑**以设置角色。
# 配置 MFA、身份验证、验证和邀请消息
借助 Amazon Cognito，您可以自定义短信和电子邮件身份验证、验证以及用户邀请消息，从而增强应用程序的安全性和用户体验。对于某些消息，您可以在基于代码的验证或一键式链接验证之间进行选择。本主题讨论如何在 Amazon Cognito 控制台中对身份验证和验证通信进行个性化设置。
在**消息模板**菜单中，您可以自定义：
+ 用于一次性密码（OTP）和多重（MFA）身份验证的电子邮件和短信模板
+ 您的 SMS 和电子邮件验证消息
+ 电子邮件的验证类型–代码或链接
**注意**
当用户注册或重新发送确认码时，Amazon Cognito 会在验证消息中发送包含您的基于链接的模板的链接。来自属性更新和密码重置操作的电子邮件使用代码模板。
+ 您的用户邀请消息
+ 流经用户池的电子邮件的 FROM 和 REPLY-TO 电子邮件地址
**注意**
只有在选择要求进行电话号码和电子邮件验证后，才会显示短信和电子邮件验证消息模板。同样，只有 MFA 设置为 **required**（必填）或 **optional**（可选）时，才会显示 SMS MFA 消息模板。
**Topics**
+ [消息模板](#cognito-user-pool-settings-message-templates)
+ [自定义电子邮件和短信 MFA 消息](#cognito-user-pool-settings-SMS-message-customization)
+ [自定义电子邮件验证消息](#cognito-user-pool-settings-email-verification-message-customization)
+ [自定义用户邀请消息](#cognito-user-pool-settings-user-invitation-message-customization)
+ [自定义您的电子邮件地址](#cognito-user-pool-settings-email-address-customization)
+ [授权 Amazon Cognito 代表您发送 Amazon SES 电子邮件（通过自定义 FROM 电子邮件地址）](#cognito-user-pool-settings-ses-authorization-to-send-email)
## 消息模板
您可以使用消息模板，在消息中插入占位符。Amazon Cognito 使用相应的值替换占位符。您可以在任何类型的消息模板中引用*通用模板占位符*，但并非所有消息类型中都会出现这些值。
**通用模板占位符**
| 说明 | 令牌 | 消息类型 |
| --- | --- | --- |
| 验证代码 | \$1\$1\$1\$1\$1\$1 | 验证、确认和 MFA 消息 |
| 临时密码 | \$1\$1\$1\$1\$1\$1 | 忘记密码和邀请消息 |
| 用户名 | \$1username\$1 | 邀请和高级安全消息 |
其中一个具有[威胁防护](cognito-user-pool-settings-threat-protection.md)的可用自动响应是通知用户，Amazon Cognito 检测到潜在恶意活动。您可以使用高级安全模板占位符执行以下操作：
+ 包括某个事件的特定详细信息，例如 IP 地址、城市、国家/地区、登录时间、设备名称。Amazon Cognito 威胁防护可以分析这些详细信息。
+ 验证一键式链接是否有效。
+ 使用事件 ID、反馈令牌和用户名构建您自己的一键式链接。
**注意**
要生成一键式链接并在高级安全电子邮件模板中使用 `{one-click-link-valid}` 和 `{one-click-link-invalid}` 占位符，您必须已经为用户池配置了域。
威胁防护功能可添加以下占位符，您可以将其插入到消息模板中。这些占位符适用于**自适应身份验证消息**，即 Amazon Cognito 向已对其会话进行风险级别评估的用户发送的通知。要使用这些变量配置消息模板，请在 Amazon Cognito 控制台中更新威胁防护的**全功能**配置，或者在请求中[SetRiskConfiguration](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetRiskConfiguration.html)提交模板。
**高级安全模板占位符**
| 说明 | 令牌 |
| --- | --- |
| IP 地址 | \$1ip-address\$1 |
| 城市 | \$1city\$1 |
| 国家/地区 | \$1country\$1 |
| 登录时间 | \$1login-time\$1 |
| 设备名称 | \$1device-name\$1 |
| 一键式链接有效 | \$1one-click-link-valid\$1 |
| 一键式链接无效 | \$1one-click-link-invalid\$1 |
| 事件 ID | \$1event-id\$1 |
| 反馈令牌 | \$1feedback-token\$1 |
## 自定义电子邮件和短信 MFA 消息
要自定义用于[多重身份验证（MFA）](user-pool-settings-mfa.md)的短信和电子邮件，请从 Amazon Cognito 用户池控制台的**消息模板**菜单编辑 **MFA 消息**。
**重要**
您的自定义消息必须包含 `{####}` 占位符。该占位符会在消息发送之前替换为身份验证代码。
Amazon Cognito 设置的短信（包括验证码）的最大长度为 140 个 UTF-8 字符。
### 自定义 SMS 验证消息
要自定义用于电话号码验证的短信，请从用户池的**消息模板**菜单编辑**验证消息**模板。
**重要**
您的自定义消息必须包含 `{####}` 占位符。该占位符会在消息发送之前替换为验证代码。
消息的最大长度为 140 个 UTF-8 字符，其中包括验证代码。
## 自定义电子邮件验证消息
要使用 Amazon Cognito 验证用户池中用户的电子邮件地址，您可以向用户发送一封电子邮件，其中包含用户可以点击的链接或可以输入的代码。
要自定义用于电子邮件地址验证消息的电子邮件主题和消息内容，请从用户池的**消息模板**菜单编辑**验证消息**模板。在编辑**验证消息**模板时，您可以选择**验证类型**，即**代码**或**链接**。
当您选择**代码**作为验证类型时，您的自定义消息必须包含 `{####}` 占位符。发送消息时，验证代码会替换占位符。
当您选择**链接**作为验证类型时，您的自定义消息必须包含格式为 `{##Verify Your Email##}` 的占位符。您可以更改占位符之间的文本字符串，例如 `{##Click here##}`。标题为 *Verify Your Email*（验证您的电子邮件）的验证链接将替换此占位符。
电子邮件验证消息的链接将您的用户定向到类似于以下示例的 URL。
```
https:///confirmUser/?client_id=abcdefg12345678&user_name=emailtest&confirmation_code=123456
```
消息的最大长度为 20000 个 UTF-8 字符，其中包括验证代码（如果有）。您可以在此消息中使用 HTML 标签来格式化内容。
## 自定义用户邀请消息
您可以通过从**消息模板**菜单编辑**邀请消息**模板，来自定义 Amazon Cognito 通过短信或电子邮件发送给新用户的用户邀请消息。
**重要**
您的自定义消息必须包含 `{username}` 和 `{####}` 占位符。当 Amazon Cognito 发送邀请消息时，它会将这些占位符替换为您用户的用户名和密码。
SMS 消息的最大长度为 140 个 UTF-8 字符，其中包括验证代码。电子邮件的最大长度为 20000 个 UTF-8 字符，其中包括验证代码。您可以在电子邮件中使用 HTML 标签来格式化内容。
## 自定义您的电子邮件地址
默认情况下，Amazon Cognito 通过 **no-reply@verificationemail.com** 向用户池中的用户发送电子邮件。您可以选择指定自定义 FROM 和 REPLY-TO 电子邮件地址来代替 **no-reply@verificationemail.com**。
**自定义 FROM 和 REPLY-TO 电子邮件地址**
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**身份验证方法**菜单。在 **Email**（电子邮件）下，选择 **Edit**（编辑）。
1. 选择 **SES Region**（SES 区域）。
1. 从在您所选 **SES Region**（SES 区域）中已经过 Amazon SES 验证的电子邮件地址列表中，选择 **FROM email address**（发件人电子邮件地址）。要使用来自经过验证的域名的电子邮件地址，请在 AWS Command Line Interface 或 AWS API 中配置电子邮件设置。有关更多信息，请参阅《Amazon Simple Email Service 开发人员指南》**中的[在 Amazon SES 中验证电子邮件地址和域](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-addresses-and-domains.html)。
1. 从您所选 **SES Region**（SES 区域）中配置集的列表中，选择 **Configuration set**（配置集）。
1. 为您的电子邮件消息输入易记且格式为 `John Stiles ` 的 **FROM sender name**（FROM 发件人名称）。
1. 要自定义 REPLY-TO 电子邮件地址，请在 **REPLY-TO email address**（REPLY-TO 电子邮件地址）字段中输入有效的电子邮件地址。
## 授权 Amazon Cognito 代表您发送 Amazon SES 电子邮件（通过自定义 FROM 电子邮件地址）
您可以将 Amazon Cognito 配置为从自定义 FROM 电子邮件地址而不是默认地址发送电子邮件。要使用自定义地址，您必须授予 Amazon Cognito 权限，才能从经过 Amazon SES 验证的身份发送电子邮件。大多数情况下，您可以创建发送授权策略来授予权限。有关更多信息，请参阅《Amazon Simple Email Service 开发人员指南》**中的[使用 Amazon SES 的发送授权](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization.html)。
当您将用户池配置为使用 Amazon SES 处理电子邮件时，Amazon Cognito 会在您的账户中创建 `AWSServiceRoleForAmazonCognitoIdpEmailService` 角色来授予对 Amazon SES 的访问权限。使用 `AWSServiceRoleForAmazonCognitoIdpEmailService` 服务相关角色时无需发送授权策略。只需在用户池中使用默认电子邮件功能*和*经过验证的 Amazon SES 身份作为 FROM 地址时，才需要添加发送授权策略。
有关 Amazon Cognito 创建的服务相关角色的更多信息，请参阅[对 Amazon Cognito 使用服务相关角色](using-service-linked-roles.md)。
以下示例发送授权策略授予 Amazon Cognito 使用经 Amazon SES 验证的身份的有限能力。Amazon Cognito 在代表 `aws:SourceArn` 中的用户池和 `aws:SourceAccount` 条件中的账户时才能发送电子邮件。有关更多示例，请参阅《Amazon Simple Email Service 开发人员指南》**中的 [Amazon SES 发送授权策略示例](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization-policy-examples.html)。
**注意**
在此示例中，“Sid”值为唯一标识语句的任意字符串。有关策略语法的更多信息，请参阅《Amazon Simple Email Service 开发人员指南》**中的 [Amazon SES 发送授权策略](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/sending-authorization-policies.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "stmnt1234567891234",
"Effect": "Allow",
"Principal": {
"Service": [
"email.cognito-idp.amazonaws.com"
]
},
"Action": [
"SES:SendEmail",
"SES:SendRawEmail"
],
"Resource": "arn:aws:ses:us-east-1:111122223333:identity/support@example.com",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:cognito-idp:us-east-1:111122223333:userpool/us-east-1_EXAMPLE"
}
}
}
]
}
```
------
当您从下拉菜单中选择 Amazon SES 身份时，Amazon Cognito 控制台会为您添加相似策略。如果您使用 CLI 或 API 配置用户池，则必须将与前例结构相同的策略附加到您的 Amazon SES 身份。
# 以管理员身份创建用户账户
用户池不仅仅是客户身份和访问管理（CIAM）用户目录，互联网上的任何人都可以在您的应用程序中注册用户配置文件。您可以禁用自助注册。您可能已经认识您的客户，并且只想接纳那些事先获得授权的客户。您可以使用[私有 SAML 2.0 或 OIDC 身份提供者](cognito-user-pools-identity-federation.md)、通过[导入用户](cognito-user-pools-import-users.md)、通过[在注册时筛选用户](user-pool-lambda-pre-sign-up.md)，或者通过使用管理 API 操作创建用户，您可以在应用程序周围设置手动身份验证护栏。您的用户管理创建工作流程可以是编程的，即在用户在其他系统中注册后对其进行配置，也可以在 Amazon Cognito 控制台中进行 case-by-case或测试。
当您以管理员身份创建用户时，Amazon Cognito 会为他们设置临时密码并发送欢迎或邀请消息。他们可以点击邀请消息中的链接进行首次登录、设置密码并确认其账户。以下页面说明了如何创建新用户和配置欢迎消息。有关使用用户池 API 和 AWS SDK 或 CDK 创建用户的更多信息，请参阅[AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html)。
创建用户池后，您可以使用 AWS 管理控制台、以及 AWS Command Line Interface 或 Amazon Cognito API 创建用户。您可以为用户池中的新用户创建配置文件，并通过 SMS 或电子邮件向用户发送带有注册说明的欢迎消息。
以下是管理员如何管理用户池中的用户的一些示例。
+ 在 Amazon Cognito 控制台中或通过 `AdminCreateUser` API 操作创建新用户配置文件。
+ 将无密码 username-and-password、密钥和自定义[身份验证流程](amazon-cognito-user-pools-authentication-flow-methods.md)提供给您的用户池和应用程序客户端。
+ 设置用户属性值。
+ 创建自定义属性。
+ 在 `AdminCreateUser` API 请求中设置不可变[自定义属性](user-pool-settings-attributes.md#user-pool-settings-custom-attributes)的值。此功能在 Amazon Cognito 控制台中不可用。
+ 指定临时密码，创建没有密码的用户，或者允许 Amazon Cognito 自动生成密码。
+ 创建新用户并自动确认其账户，验证他们的电子邮件地址或验证他们的电话号码。
+ 通过 AWS 管理控制台 或 Lambda 触发器（如自定义消息、自定义短信发送器和[自定义电子邮件发[件人）为新用户指定自定义短信](user-pool-lambda-custom-sms-sender.md)和[电子邮件](user-pool-lambda-custom-email-sender.md)邀请消息](user-pool-lambda-custom-message.md)。
+ 指定是否通过 SMS、电子邮件或两者发送邀请消息。
+ 通过调用 `AdminCreateUser` API，并为 `RESEND` 参数指定 `MessageAction`，向现有用户重新发送欢迎消息。
+ 创建用户时[禁止](#admincreateuserwalkthrough-step-invitationmessage)发送邀请消息。
+ 为新用户账户指定长达 90 天的到期时间限制。
+ 允许用户自行注册或要求只能由管理员添加新用户。
管理员还可以在服务器端应用程序中使用 AWS 凭据登录用户。有关更多信息，请参阅 [API 和 SDK 身份验证的授权模型](authentication-flows-public-server-side.md)。
## 用户身份验证流程和创建用户
根据用户池的配置，以管理员身份创建用户的选项会有所不同。*身份验证流程*或可供用户登录和 MFA 的方法可以更改您创建用户以及向他们发送的消息的方式。以下是用户池中可用的一些身份验证流程。
+ 用户名和密码
+ 通行密钥
+ 使用第三方登录 IdPs
+ 无需密码，使用电子邮件和短信一次性密码 () OTPs
+ 使用电子邮件、短信和身份验证器应用程序进行多因素身份验证 OTPs
+ 使用 Lambda 触发器的自定义身份验证
有关如何配置这些登录因素的更多信息，请参阅[使用 Amazon Cognito 用户池进行身份验证](authentication.md)。
## 创建无密码用户
如果您为用户池启用了无密码登录，则可以创建无密码用户。要创建无密码用户，必须为可用的无密码登录因素提供属性值。例如，如果您的用户池中提供电子邮件 OTP 无密码登录，则可以创建一个没有密码和电子邮件地址属性的用户。如果新用户只能通过密码执行身份验证流程，例如通行密钥或用户名密码，则必须为每个新用户创建或生成临时密码。
**创建新的无密码用户**
+ 在 Amazon Cognito 控制台中选择**请勿设置密码**
+ 忽略 `AdminCreateUser` API 请求的 `TemporaryPassword` 参数或将其留空
**无密码用户会自动得到确认**
通常，当您创建新用户时，他们会获得临时密码并进入 `FORCE_CHANGE_PASSWORD` 状态。当您创建无密码用户时，他们会立即进入 `CONFIRMED` 状态。您无法向这些处于 `CONFIRMED` 状态的用户重新发送确认码。
**邀请消息会针对无密码用户发生变化。**
默认情况下，Amazon Cognito 会向新用户发送一条[邀请消息](cognito-user-pool-settings-message-customizations.md#cognito-user-pool-settings-user-invitation-message-customization)，显示 `Your username is {userName} and your password is {####}.`。当您创建无密码用户时，消息会显示为 `Your username is {userName}.`。自定义您的邀请消息，以反映您是否要为用户设置密码。请在无密码身份验证模型中忽略 `{####}` 密码变量。
**当无密码因素可用时，您无法自动生成密码**
如果您已将用户池配置为支持电子邮件或电话 OTP 无密码登录，则无法自动生成密码。对于每位将拥有密码的用户，在创建其配置文件时都必须设置一个临时密码。
**无密码用户必须具有所有必需属性的值**
在创建*无*密码用户时，只有当用户为用户池中已标记为必填的所有属性都提供值时，您的请求才会成功。这适用于任何必需属性，而不仅仅是发送 OTP 所需的电话号码和电子邮件属性。
## 创建稍后将提供必需属性值的用户
您可能想在用户池中要求提供属性，但在以管理员身份创建用户之后，在应用程序中的用户交互期间收集这些属性。管理员可以在使用*临时密码*创建用户时忽略必需属性的值。您不能忽略无密码用户的必需属性值。
缺少必需属性值且使用临时密码的用户在首次登录时会收到 [NEW\$1PASSWORD\$1REQUIRED](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html#CognitoUserPools-RespondToAuthChallenge-request-ChallengeResponses) 质询。然后，他们可以在 `requiredAttributes` 参数中为缺少的必需属性提供一个值。只有当所有必需属性都[可变](user-pool-settings-attributes.md#user-pool-settings-custom-attributes)时，才能创建带有密码但没有必需属性的用户。只有当必需属性可从用户登录时使用的应用程序客户端[写入](user-pool-settings-client-apps.md#cognito-user-pools-app-idp-settings-about)时，用户才能通过 `NEW_PASSWORD_REQUIRED` 质询和必需属性值完成登录。
当您为管理员创建的用户设置永久密码时，他们的状态会更改为 `CONFIRMED`，并且您的用户池在他们首次登录时不会提示他们输入新密码*或*必需属性。
## 在中创建新用户 AWS 管理控制台
您可以设置用户密码要求、配置发送给用户的邀请和验证消息，以及使用 Amazon Cognito 控制台添加新用户。
### 设置密码策略并启用自行注册
您可以配置设置以最大限度地降低密码复杂性，以及用户是否可以在您的用户池 APIs 中使用公共方式进行注册。
**配置密码策略**
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**身份验证方法**菜单并找到**密码策略**。选择**编辑**。
1. 选择**自定义**的**密码策略模式**。
1. 选择**密码最小长度**。有关密码长度要求的限制，请参阅[用户池资源配额](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html#limits-hard)。
1. 选择**密码复杂性**要求。
1. 选择管理员设置的密码应在多长时间内有效。
1. 选择**保存更改**。
**允许自助注册**
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**注册**菜单并找到**自助注册**。选择**编辑**。
1. 选择是否**启用自助注册**。自助注册通常用于需要在不分发客户端密钥或 AWS Identity and Access Management (IAM) API 凭证的情况下在用户池中注册新用户的公共应用程序客户端。
**禁用自助注册**
如果您不启用自助注册，则必须通过使用 IAM API 凭证的管理 API 操作或通过联合提供商登录来创建新用户。
1. 选择**保存更改**。
### 自定义电子邮件和 SMS 消息
**自定义用户消息**
当您邀请用户登录、注册用户账户或登录并提示用户进行多重身份验证（MFA）时，您可以自定义 Amazon Cognito 发送给用户的消息。
**注意**
当您在用户池中创建用户并邀请他们登录时将发送**邀请消息**。Amazon Cognito 将初始登录信息发送到用户的电子邮件地址或电话号码。
当用户在您的用户池中注册用户账户时将发送**验证消息**。Amazon Cognito 向用户发送代码。当用户向 Amazon Cognito 提供代码时，他们会验证自己的联系人信息并确认自己的账户以进行登录。验证代码的有效期为 24 小时。
当您在用户池中启用 SMS MFA，并且已配置 SMS MFA 的用户登录并提示输入 MFA 时，将发送 **MFA 消息**。
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**消息模板**菜单并选择**验证消息**、**邀请消息**或 **MFA 消息**，然后选择**编辑**。
1. 自定义所选消息类型的消息。
**注意**
自定义消息时，必须包括消息模板中的所有变量。如果变量（例如，**\$1\$1\$1\$1\$1\$1**）不包括在内，您的用户将没有足够的信息来完成消息操作。
有关更多信息，请参阅[消息模板](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-message-templates.html)。
1.
1. **验证消息**
1. 选择用于**电子邮件**消息的**验证类型**。**代码**验证将发送用户必须输入的数字代码。**链接**验证将发送一个链接，用户可以点击该链接以验证其联系人信息。用于**链接**消息变量中的文本显示为超链接文本。例如，使用变量 \$1\$1\$1Click here\$1\$1\$1 的消息模板在电子邮件中显示为[单击此处]()。
1. 输入用于**电子邮件**消息的**电子邮件主题**。
1. 输入用于**电子邮件**消息的自定义**电子邮件消息**模板。您可以使用 HTML 自定义此模板。
1. 输入用于 **SMS** 消息的自定义 **SMS 消息**模板。
1. 选择**保存更改**。
1. **邀请消息**
1. 输入用于**电子邮件**消息的**电子邮件主题**。
1. 输入用于**电子邮件**消息的自定义**电子邮件消息**模板。您可以使用 HTML 自定义此模板。
1. 输入用于 **SMS** 消息的自定义 **SMS 消息**模板。
1. 选择**保存更改**。
1. **MFA 消息**
1. 输入用于 **SMS** 消息的自定义 **SMS 消息**模板。
1. 选择**保存更改**。
### 创建用户
**创建用户**
您可以从 Amazon Cognito 控制台为用户池创建新用户。通常，用户可以在设置密码后登录。要使用电子邮件地址登录，用户必须验证 `email` 属性。要使用电话号码登录，用户必须验证 `phone_number` 属性。要以管理员身份确认账户，您还可以使用 AWS CLI 或 API，或者使用联合身份提供商创建用户个人资料。有关更多信息，请参阅 [Amazon Cognito API 参考](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/)。
1. 导航到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)，选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**用户**菜单，然后选择**创建用户**。
1. 检查**用户池登录和安全要求**以获取有关密码要求、可用的账户恢复方法和用户池的别名属性的指导。
1. 选择您希望如何发送**邀请消息**。选择 SMS 消息和/或电子邮件消息。要禁止邀请消息，请选择**不要发送邀请**。
**注意**
在您可以发送邀请消息之前，请在用户池的**身份验证方法**菜单中使用 Amazon Simple Notification Service 和 Amazon Simple Email Service 配置发件人和 AWS 区域 。收件人消息和数据费率适用。Amazon SES 单独向您收取电子邮件消息费用，Amazon SNS 单独向您收取 SMS 消息费用。
1. 选择用于新用户的**用户名**。
1. 选择您是要为用户**创建密码**，还是让 Amazon Cognito **生成密码**。如果用户池中提供[无密码登录](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)，则生成密码的选项不可用。任何临时密码都必须遵守用户池密码策略。
1. 选择**创建**。
1. 选择**用户**菜单，然后选择用户的**用户名**条目。添加和编辑**用户属性**和**组成员资格**。查看**用户事件历史记录**。
# 向用户池添加组
借助对 Amazon Cognito 用户池中组的支持，您可以创建和管理组、将用户添加到组以及从组中删除用户。使用组可创建用户集合以管理其权限或表示不同类型的用户。您可以为群组分配 AWS Identity and Access Management (IAM) 角色来定义群组成员的权限。
您可以使用组以在用户池中创建用户集合，这通常用于为这些用户设置权限。例如，您可以为作为您网站和应用程序的读者、贡献者或编辑者的用户创建单独的组。通过使用与组关联的 IAM 角色，您还可以为那些不同的组设置不同的权限，从而只有贡献者可以将内容放置在 Amazon S3 中，并且只有编辑者可以通过 Amazon API Gateway 中的 API 发布内容。
Amazon Cognito 会为您添加到用户池中的每个 OIDC 和社交身份[提供商 (](cognito-user-pools-identity-federation.md#cognito-user-pools-identity-federation-how-it-works)IdP) 创建一个用户组。 SAMl该组的名称采用 `[user pool ID]_[IdP name]` 格式，例如 `us-east-1_EXAMPLE_MYSSO` 或 `us-east-1_EXAMPLE_Google`。每个自动生成的唯一 IdP 用户配置文件都会自动添加到该组。[关联用户](cognito-user-pools-identity-federation-consolidate-users.md)不会自动添加到该组，但您可以通过另外的流程将其配置文件添加到该组。
您可以通过、和 CLI 在用户池中 AWS 管理控制台创建和管理群组。 APIs作为开发者（使用 AWS 证书），您可以创建、读取、更新、删除和列出用户池的群组。您还可以将用户添加到组和从组中删除用户。
在用户池中使用组不会产生额外费用。有关更多信息，请参阅 [Amazon Cognito 定价](https://aws.amazon.com/cognito/pricing/)。
## 向组分配 IAM 角色
您可以使用组通过 IAM 角色控制资源的权限。IAM 角色包含信任策略和权限策略。角色的[信任](https://docs.aws.amazon.com/cognito/latest/developerguide/role-trust-and-permissions.html)策略指定谁可使用该角色。[权限](https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html#access-policies)策略指定组成员可以访问的操作和资源。在您创建 IAM 角色时，请设置角色的信任策略以允许您的组用户担任该角色。请在角色的权限策略中，指定您希望组具有的权限。
在 Amazon Cognito 中创建组时，可以通过提供角色的 [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns) 指定 IAM 角色。当组成员使用 Amazon Cognito 登录时，他们可以从身份池接收临时凭证。他们的权限由关联的 IAM 角色确定。
单个用户可处于多个组中。作为开发人员，当一个用户位于多个组中时，您可以使用以下选项自动选择 IAM 角色：
+ 您可以为每个组分配优先级值。将选择优先级较高（值较低）的组，并应用其关联的 IAM 角色。
+ 在通过身份池为用户请求 AWS 凭证时，您的应用程序还可以在参数中指定角色 ARN，从可用角色中[GetCredentialsForIdentity](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_GetCredentialsForIdentity.html)`CustomRoleARN`进行选择。指定的 IAM 角色必须与适用于用户的角色相匹配。
## 将优先级值分配到组
一个用户可属于多个组。在用户的访问令牌和 ID 令牌中，`cognito:groups` 声明包含用户所属的所有组的列表。`cognito:roles` 断言包含与这些组对应的角色列表。
由于一个用户可以属于多个组，因此可为每个组分配一个优先级。这是一个非负数值，用于指定该组相对于用户池中用户所属其它组的优先级。零是代表最高优先级的值。具有较低优先级值的组优先于具有较高或空优先级值的组。如果一个用户属于两个或更多组，则具有最低优先级值的组的 IAM 角色将应用于用户 ID 令牌中的 `cognito:preferred_role` 声明。
两个组可以具有相同的优先级值。如果发生这种情况，则两个组之间不存在优先情况。如果具有相同优先级值的两个组还具有相同的角色 ARN，则该角色将用于每个组中用户的 ID 令牌的 `cognito:preferred_role` 陈述。如果两个群组的角色不同 ARNs，则不会在用户的 ID 令牌中设置`cognito:preferred_role`声明。
## 使用组控制使用 Amazon API Gateway 的权限
您可以使用用户池中的组控制使用 Amazon API Gateway 的权限。用户所属的组包含在 `cognito:groups` 声明中的用户池的 ID 令牌和访问令牌中。您可以通过请求向 Amazon API Gateway 提交 ID 或访问令牌，并使用 Amazon Cognito 用户池授权方获取 REST API。有关更多信息，请参阅[《API Gateway 开发人员指南》](https://docs.aws.amazon.com/apigateway/latest/developerguide/)中的[使用 Amazon Cognito 用户池作为授权方控制对 REST API 的访问](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-integrate-with-cognito.html)。
您还可以使用自定义 JWT 授权方授权访问 Amazon API Gateway HTTP API。有关更多信息，请参阅《[API Gateway 开发](https://docs.aws.amazon.com/apigateway/latest/developerguide/)者指南》中的 “[ APIs 使用 JWT 授权者控制 HTTP 访问权限](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html)”。
## 组的限制
用户组受以下限制的约束：
+ 您可以创建的组的数量受 [Amazon Cognito 服务配额](quotas.md)的限制。
+ 不能对组进行嵌套。
+ 不能搜索组中的用户。
+ 不能按名称搜索组，但可以列出组。
## 在中创建新群组 AWS 管理控制台
使用以下过程创建新组。
**创建新组。**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**组**菜单，然后选择**创建组**。
1. 在 **Create a group**（创建组）页面的 **Group name**（组名称）中，为您的新组输入一个易记名称。
1. 您可以选择使用以下任意字段提供有关此组的其它信息：
+ **Description**（说明）– 输入有关这个新组将用于什么的详细信息。
+ **Precedence**（优先顺序）– Amazon Cognito 根据给定用户所属群组具有的较低优先级值，评估并应用所有群组权限。将选择优先级较低的组，并应用其关联的 IAM 角色。有关更多信息，请参阅 [将优先级值分配到组](#assigning-precedence-values-to-groups)。
+ **IAM role**（IAM 角色）– 当您需要控制对资源的权限时，您可以为组分配 IAM 角色。如果您要将用户池与身份池集成，并且身份池配置为从令牌中选择角色，则 **IAM role (IAM 角色)** 设置将确定在用户的 ID 令牌中分配哪个角色。有关更多信息，请参阅 [向组分配 IAM 角色](#assigning-iam-roles-to-groups)。
+ **Add users to this group**（将用户添加到此组）– 创建后将现有用户添加为该组的成员。
1. 选择 **Create**（创建）以确认。
# 管理和搜索用户账户
用户池可以包含数百万个用户。对于管理员来说，使用这种规模的数据集是一项挑战。Amazon Cognito 提供了用于查找和修改用户配置文件的工具。查找用户的主要方法是 Amazon Cognito 控制台的 “**用户**” 菜单，以及。[ListUsers](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html)在检索用户信息的方法中，这些选项不会像例如那样对成本产生影响[AdminGetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminGetUser.html)。
本指南的这一部分包含有关在用户池中查找和更新用户配置文件的信息。
## 查看用户属性
请使用以下过程在 Amazon Cognito 控制台中查看用户属性。
**查看用户属性**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后在列表中选择用户。
1. 在用户详细信息页面，您可以在 **User attributes**（用户属性）中查看哪些属性与用户关联。
## 重置用户的密码
请使用以下过程在 Amazon Cognito 控制台重置用户的密码。
**重置用户的密码**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后在列表中选择用户。
1. 在用户详细信息页面上，选择 **Actions**（操作）、**Reset password**（重置密码）。
1. 在 **Reset password**（重置密码）对话框中，查看信息，准备就绪后，选择 **Reset**（重置）。
该操作会立即导致向用户发送确认代码，并通过将用户状态更改为 `RESET_REQUIRED` 来禁用用户的当前密码。**Reset password**（重置密码）代码的有效期为 1 小时。
## 启用、禁用和删除用户账户
您可以删除未使用的用户配置文件，或者如果您想临时阻止访问，可将其禁用。用户可以删除自己的账户，但只有用户池管理员才能启用和禁用用户账户。
**删除的影响**
用户无法使用已删除的用户账户登录，要重新获得访问权限，必须注册或重新创建用户。
**禁用账户的影响**
当您禁用用户账户时，Amazon Cognito 会自动使所有经过身份验证的会话失效，停用用户账户的登录，并[撤销他们的访问权限和刷新令牌](token-revocation.md)。当用户尝试登录您禁用的账户时，Amazon Cognito 会返回 `invalid_request` 错误及 `User is not enabled` 消息。这种行为不会随着应用程序客户端的[用户存在披露设置](cognito-user-pool-managing-errors.md)而改变。您可以禁用本地用户账户和联合用户账户的本地配置文件。当用户通过托管登录或经典的托管 UI 登录，然后您禁用其账户，在他们尝试使用维护其经过身份验证的会话的浏览器 Cookie 再次登录时，Amazon Cognito 会将他们重定向到登录页面。
**启用账户的影响**
启用账户后，用户可以立即登录账户。默认情况下，用户账户处于启用状态。用户的属性和密码与其账户被禁用之前相同。无论您是禁用用户账户还是单独撤销刷新令牌，您的应用程序撤销的令牌在您启用拥有该令牌的用户账户后都将保持无效。
------
#### [ Delete a user account (console) ]
**删除用户账户**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后选中列表中用户名旁边的单选按钮。
1. 选择**删除**。
1. 选择**禁用用户访问**。
1. 选择**删除**。
------
#### [ Delete a user account (API) ]
用户可以通过自助服务 access-token-authorized [DeleteUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUser.html)API 操作删除其账户。以下是一个示例 `DeleteUser` 请求正文。
```
{
"AccessToken": "eyJra456defEXAMPLE"
}
```
管理员可以通过 IAM 授权的 [AdminDeleteUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDeleteUser.html)API 操作删除用户帐户。以下是一个示例 `AdminDeleteUser` 请求正文。
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
#### [ Disable a user account (console) ]
**禁用用户账户**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后在列表中选择用户的用户名。
1. 在用户详细信息页面上，选择**操作**、**禁用用户访问**。
1. 在由此创建的对话框中，选择**禁用**。
------
#### [ Disable a user account (API) ]
管理员可以通过 IAM 授权的 [AdminDisableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminDisableUser.html)API 操作禁用用户帐户。以下是一个示例 `AdminDisableUser` 请求正文。
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
#### [ Enable a user account (console) ]
**启用用户账户**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。如果出现提示，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后在列表中选择用户的用户名。
1. 在用户详细信息页面上，选择**操作**、**启用用户访问**。
1. 在由此创建的对话框中，选择**启用**。
------
#### [ Enable a user account (API) ]
管理员可以通过 IAM 授权的 [AdminEnableUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminEnableUser.html)API 操作启用用户帐户。以下是一个示例 `AdminEnableUser` 请求正文。
```
{
"Username": "testuser",
"UserPoolId": "us-west-2_EXAMPLE"
}
```
------
## 搜索用户属性
如果您已创建用户池，则可以在 AWS 管理控制台的 **Users**（用户）面板中搜索。您也可以使用 Amazon Cognito [ListUsers API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html)，它接受**筛选**器参数。
您可以搜索以下任何标准属性。自定义属性不可搜索。
+ username（区分大小写）
+ email
+ phone\$1number
+ name
+ given\$1name
+ family\$1name
+ preferred\$1username
+ cognito:user\$1status（在控制台中称为**Status**（状态））（区分大小写）
+ status（在控制台中称为**Enabled**（已启用））（区分大小写）
+ sub
**注意**
您还可以使用客户端筛选条件列出用户。服务器端筛选条件匹配的属性不超过 1 个。对于高级搜索，请使用客户端筛选条件，其中包含 AWS Command Line Interface中 `list-users` 操作的 `--query` 参数。使用客户端筛选器时，会 ListUsers 返回零个或多个用户的分页列表。您可以连续接收多个结果为零的页面。对返回的每个分页令牌重复查询，直到您收到一个空的分页令牌值，然后查看合并结果。
有关服务器端和客户端筛选的更多信息，请参阅《 AWS Command Line Interface 用户指南》中的[筛选 AWS CLI 输出](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-filter.html)。
## 使用搜索用户 AWS 管理控制台
如果您已创建用户池，则可以在 AWS 管理控制台的 **Users**（用户）面板中搜索。
AWS 管理控制台 搜索始终是前缀（“以” 开头）搜索。
**在 Amazon Cognito 控制台中搜索用户**
1. 转到 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。系统可能会提示您输入 AWS 凭证。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**用户**菜单，然后在搜索字段中输入用户名。请注意，某些属性值区分大小写 [例如，**Username**（用户名）]。
您还可以通过调整搜索筛选条件来查找用户，将范围缩小到其它用户属性，如 **Email**（电子邮件）、**Phone number**（电话号码）或 **Last name**（姓）。
## 使用 `ListUsers` API 搜索用户
[要从您的应用程序中搜索用户，请使用亚马逊 Cognito ListUsers API。](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html)此 API 使用以下参数：
+ `AttributesToGet`：一组字符串，其中每个字符串均为将针对搜索结果中的每位用户返回的用户属性的名称。要检索所有属性，请不要包含 `AttributesToGet` 参数或文本字符串值为 `null` 的请求 `AttributesToGet`。
+ `Filter`：筛选条件字符串，格式为 "`AttributeName` `Filter-Type` "`AttributeValue`""。筛选条件字符串中的引号必须使用反斜杠 (`\`) 字符进行转义。例如 `"family_name = \"Reddy\""`。如果筛选条件字符串为空，`ListUsers` 将返回用户池中的所有用户。
+ `AttributeName`：要搜索的属性的名称。一次只能搜索一个属性。
**注意**
您只能搜索标准属性。自定义属性不可搜索。这是因为只有索引属性可搜索，而自定义属性不可索引。
+ `Filter-Type`：对于精确匹配，请使用 `=`，例如 `given_name = "Jon"`。对于前缀 (“starts with”) 匹配，请使用 `^=`，例如 `given_name ^= "Jon"`。
+ `AttributeValue`：必须为每位用户匹配的属性值。
+ `Limit`：要返回的最大用户数。
+ `PaginationToken`：可从之前的搜索中获取更多结果的令牌。Amazon Cognito 会在一小时后让分页令牌过期。
+ `UserPoolId`：应对其执行搜索的用户池的用户池 ID。
所有搜索都区分大小写。搜索结果按以 `AttributeName` 字符串命名的属性进行升序排列。
## 使用 `ListUsers` API 的示例
以下示例将返回所有用户并包括所有属性。
```
{
"AttributesToGet": null,
"Filter": "",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
以下示例将返回电话号码以“\$11312”开头的所有用户并包括所有属性。
```
{
"AttributesToGet": null,
"Filter": "phone_number ^= \"+1312\"",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
以下示例将返回姓氏为“Reddy”的前 10 位用户。对于每个用户，搜索结果包含用户的名字、电话号码和电子邮件地址。如果用户池中有 10 个以上相匹配的用户，则响应将包含一个分页标记。
```
{
"AttributesToGet": [
"given_name",
"phone_number",
"email"
],
"Filter": "family_name = \"Reddy\"",
"Limit": 10,
"UserPoolId": "us-east-1_samplepool"
}
```
如果上一示例返回分页标记，则以下示例将返回与同一筛选条件字符串相匹配的接下来的 10 位用户。
```
{
"AttributesToGet": [
"given_name",
"phone_number",
"email"
],
"Filter": "family_name = \"Reddy\"",
"Limit": 10,
"PaginationToken": "pagination_token_from_previous_search",
"UserPoolId": "us-east-1_samplepool"
}
```
# 密码、账户恢复和密码策略
所有登录到用户池的用户（甚至是[联合用户](cognito-terms.md#terms-federateduser)）都为其用户配置文件分配了密码。[本地用户](cognito-terms.md#terms-localuser)和[关联用户](cognito-terms.md#terms-linkeduser)在登录时必须提供密码。联合用户不使用用户池密码，而是使用其身份提供者（IdP）登录。您可以允许用户自行重置密码、以管理员身份重置或更改密码，以及[设置密码复杂度和历史策略](#user-pool-settings-policies)。
Amazon Cognito 不以明文形式存储用户密码。而是通过用户特定的加密盐来存储每个用户密码的哈希值。因此，您无法从用户池中的用户配置文件检索现有密码。作为一项最佳实践，请不要在任何地方存储明文用户密码。当用户忘记密码时，执行密码重置。
## 密码重置和恢复
用户忘记了自己的密码。您可能希望他们能够自己重置密码，或者您可能希望由管理员为他们重置密码。Amazon Cognito 用户池有这两种模式的选项。指南的这一部分介绍用户池设置和用于密码重置的 API 操作。
[ForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html)API 操作和托管登录选项**忘记密码了吗？** 向用户发送验证码，当他们确认自己拥有正确的密码时，他们便有机会设置新密码[ConfirmForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html)。这是自助式密码恢复模式。
**恢复未经验证的用户**
您可以向已验证其电子邮件地址或电话号码的用户发送恢复消息。如果他们没有已确认的恢复电子邮件或电话，用户池管理员可以将其电子邮件地址或电话号码标记为已验证。在 Amazon Cognito 控制台中编辑用户的**用户属性**，然后选中**将电话号码标记为已验证**或**将电子邮件地址标记为已验证**旁边的复选框。您也可以在[AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)请求中将`email_verified`或设置`phone_number_verified`为 true。对于新用户，[ResendConfirmationCode](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ResendConfirmationCode.html)API 操作会向他们的电子邮件地址或电话号码发送新的验证码，他们就可以完成自助确认和验证。
**以管理员身份重置密码**
[AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html)和 [AdminResetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminResetUserPassword.html)API 操作是管理员启动的密码重置方法。 `AdminSetUserPassword`设置临时或永久密码，并以与相同的方式`AdminResetUserPassword`向用户发送密码重置代码。`ForgotPassword`
### 配置密码重置和恢复
Amazon Cognito 会根据您在控制台中创建用户池时选择的必需属性和登录选项自动选择您的账户恢复选项。您可以修改这些默认设置。
用户首选 MFA 方法会影响他们可用于恢复密码的方法。首选 MFA 方式为电子邮件的用户无法通过电子邮件接收密码重置代码。首选 MFA 方式为短信的用户无法通过短信接收密码重置代码。
当用户不符合条件，无法使用首选密码重置方法时，您的[密码恢复](#user-pool-password-reset-and-recovery)设置必须提供替代选项。例如，您的恢复机制可能将电子邮件列为第一优先选项，而电子邮件 MFA 可能是您的用户池中的一个选项。在这种情况下，添加短信消息账户恢复作为第二个选项，或者使用管理 API 操作为这些用户重置密码。
对于没有有效恢复方式的用户发起的密码重置请求，Amazon Cognito 会返回 `InvalidParameterException` 错误响应。
**注意**
用户无法在同一电子邮件地址或电话号码上接收 MFA 验证码和密码重置验证码。如果他们使用电子邮件中的一次性密码 (OTPs) 进行 MFA，则必须使用 SMS 消息进行账户恢复。如果他们使用 OTPs 来自短信的 MFA，则必须使用电子邮件进行账户恢复。在具有 MFA 的用户池中，如果用户有电子邮件地址的属性但没有电话号码，或者有电话号码但没有电子邮件地址，则他们可能无法完成自助密码恢复。
要防止用户无法在使用此配置的用户池中重置密码的情况，请设置 `email` 和 `phone_number` [属性（按需设置）](user-pool-settings-attributes.md)。或者，您可以设置相关流程，在用户注册时或管理员创建用户配置文件时，始终收集并设置这些属性。当用户同时具备这两个属性时，Amazon Cognito 会自动将密码重置验证码发送到*不是*用户 MFA 因素的目的地。
以下过程在用户池中配置自助账户恢复。
------
#### [ Configure self-service password reset (API/SDK) ]
该`AccountRecoverySetting`参数是用户池参数，用于设置用户在 [ForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html)API 请求中或选择 “**忘记密码？” 时可以用来恢复密码**的方法。 在托管登录中。 `ForgotPassword`向经过验证的电子邮件或经过验证的电话号码发送恢复码。恢复代码的有效期为 1 小时。当您为用户池指定 [AccountRecoverySetting](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AccountRecoverySettingType.html) 时，Amazon Cognito 会根据您设置的优先级选择代码发送目标。
当您定义 `AccountRecoverySetting` 并且用户配置了 SMS MFA 时，不能将 SMS 用作账户恢复机制。此设置的优先级已确定，其中 `1` 为最高优先级。Amazon Cognito 仅向指定方法之一发送验证。以下示例 `AccountRecoverySetting` 将电子邮件地址设置为账户恢复代码的主要目标，如果用户没有电子邮件地址属性，则回退到短信。
```
"AccountRecoverySetting": {
"RecoveryMechanisms": [
{
"Name": "verified_email",
"Priority": 1
},
{
"Name": "verified_phone_number",
"Priority": 2
}
]
}
```
值 `admin_only` 会关闭自助账户恢复，而是要求用户联系他们的管理员进行密码重置。您不能将 `admin_only` 与任何其他账户恢复机制一起使用。以下
```
"AccountRecoverySetting": {
"RecoveryMechanisms": [
{
"Name": "admin_only",
"Priority": 1
}
]
}
```
如果未指定 `AccountRecoverySetting`，Amazon Cognito 会先将恢复码发送到经过验证的电话号码，如果用户没有电话号码属性，则会发送到经过验证的电子邮件地址。
有关 `AccountRecoverySetting` 的更多信息，请参阅 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)和 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)。
------
#### [ Configure self-service password reset (console) ]
从用户池的**登录**菜单配置账户恢复和密码重置选项。
**设置用户账户恢复**
1. 登录 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。
1. 选择**用户池**。
1. 从列表中选择一个现有用户池，或[创建一个用户池](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-as-user-directory.html)。
1. 选择**登录**菜单。找到**用户账户恢复**，然后选择**编辑**。
1. 要允许用户重置自己的密码，请选择**启用自助账户恢复**。
1. 为用户池发送给用户的密码恢复代码配置发送方式。在**用户账户恢复消息的发送方法**下，选择一个可用选项。最佳做法是，选择具有辅助消息发送方法的选项，例如**如果电子邮件可用，则使用电子邮件发送，否则使用短信**。借助辅助发送方法，Amazon Cognito 在向用户发送代码时，可以要求用户使用与 MFA 不同的媒介来重置密码。
1. 选择**保存更改**。
------
### 忘记密码行为
在给定时间内，作为忘记密码和操作的一部分，我们允许用户尝试请求或输入密码重置码 5 到 20 次。 confirm-forgot-password确切的值取决于与请求关联的风险参数。请注意，这种行为可能会发生变化。
## 添加用户池密码要求
作为用户池的最佳安全实践，应该设置强大、复杂的密码。特别是在对互联网开放的应用程序中，弱密码会将用户的凭证暴露给会猜测密码并尝试访问您的数据的系统。密码越复杂，就越难猜出。Amazon Cognito 为注重安全的管理员提供了其他工具 ACLs，例如[威胁防护](cognito-user-pool-settings-threat-protection.md#cognito-user-pool-settings-threat-protection.title)和[AWS WAF 网络](user-pool-waf.md#user-pool-waf.title)，但是您的密码策略是用户目录安全的核心要素。
Amazon Cognito 用户池中本地用户的密码不会自动过期。妥善的做法是在外部系统中记录用户密码重置的时间、日期和元数据。通过记录密码使用期限的外部日志，您的应用程序或 Lambda 触发器可以查找用户的密码使用期限，并在给定时间后要求重置。
您可以将用户池配置为要求密码具有最低复杂性，以符合您的安全标准。复杂密码的最小长度为至少八个字符。还必须包括大写字母、数字和特殊字符的组合。
通过基础版或增值版功能计划，您还可以设置密码重用策略。您可以阻止用户将其新密码重置为与其当前密码相同，也不得与最多 23 个以前的其他密码中的任何一个相同，即用户不能将新密码设置为这 24 个密码中的任何一个。
**设置用户池密码策略**
1. 创建一个用户池并导航到**配置安全要求**步骤，或访问现有用户池并导航到**身份验证方法**菜单。
1. 导航到**密码策略**。
1. 选择**密码策略模式**。**Cognito 默认**使用推荐的最低设置来配置您的用户池。您也可以选择一项**自定义**密码策略。
1. 设置**密码最小长度**。所有用户都必须使用长度大于或等于这个值的密码进行注册或创建。您可以将这个最小值设置为 99，但用户可以设置最长 256 个字符的密码。
1. 在**密码要求**下配置密码的复杂性规则。选择您希望在每个用户的密码中至少包含一个的字符类型（数字、特殊字符、大写字母和小写字母）。
可以要求密码中至少包含以下字符之一：在 Amazon Cognito 确认密码中包含所需的最少字符后，用户的密码可以包含任何类型的额外字符，但不得超过最大密码长度。
+ 大写和小写[基本拉丁](https://en.wikipedia.org/wiki/ISO_basic_Latin_alphabet)字母
+ 数字
+ 以下特殊字符。
```
^ $ * . [ ] { } ( ) ? " ! @ # % & / \ , > < ' : ; | _ ~ ` = + -
```
+ 非前导、非结尾的空格字符。
1. 为**管理员设置的临时密码到期时间**设置一个值。超过此期限，您通过 Amazon Cognito 控制台或 `AdminCreateUser` 创建的新用户将无法登录和设置新密码。使用临时密码登录后，他们的用户账户永远不会过期。要在 Amazon Cognito 用户池 API 中更新密码时长，请在您的[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)或 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)API 请求[TemporaryPasswordValidityDays ](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_PasswordPolicyType.html#CognitoUserPools-Type-PasswordPolicyType-TemporaryPasswordValidityDays)中为设置一个值。
1. 为**防止使用之前的密码**设置一个值（如果有）。要使用此功能，请在用户池中选择基础版或增值版[功能计划](cognito-sign-in-feature-plans.md)。此参数的值是在用户重置密码时阻止新密码匹配的先前密码数。
要重置已过期用户账户的访问权限，请执行以下操作之一：
+ 发送新的临时密码并使用已`MessageAction`设置为的 [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html)API 请求重置过期时间`RESEND`。
+ 删除用户配置文件并创建新的用户配置文件。
+ 在 [AdminResetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminResetUserPassword.html)API 请求中生成新的确认码。
# 将用户导入一个用户池
您可以使用以下两种方式将用户从现有用户目录或用户数据库导入或迁移到 Amazon Cognito 用户池中。您可以利用用户迁移 Lambda 触发器，在用户首次使用 Amazon Cognito 登录时迁移用户。借助这种方法，用户可以继续使用其现有的密码，不必在迁移到用户池后重置密码。或者，您可以上传 CSV 文件 (包含所有用户的用户配置文件属性)，批量迁移用户。以下各部分分别介绍了这两种方法。
**更多资源**
+ [将用户迁移到 Amazon Cognito 用户池的方法](https://aws.amazon.com/blogs/security/approaches-for-migrating-users-to-amazon-cognito-user-pools/)
+ [AWS re: inforce 2023-迁移到亚马逊 Cognito](https://www.youtube.com/watch?v=OkDj9uXWwCc)
**Topics**
+ [利用用户迁移 Lambda 触发器导入用户](cognito-user-pools-import-using-lambda.md)
+ [通过 CSV 文件将用户导入用户池中](cognito-user-pools-using-import-tool.md)
# 利用用户迁移 Lambda 触发器导入用户
使用这种方法，当用户首次登录您的应用程序或请求重置密码时，您可以将用户从现有用户目录无缝迁移到用户池。向您的用户池添加一个 [迁移用户 Lambda 触发器](user-pool-lambda-migrate-user.md) 函数，它会接收有关尝试登录的用户的元数据，并从外部身份源返回用户配置文件信息。有关此 Lambda 触发器的详细信息以及示例代码（包括请求和响应参数），请参阅[迁移用户 Lambda 触发器参数](user-pool-lambda-migrate-user.md#cognito-user-pools-lambda-trigger-syntax-user-migration)。
在开始迁移用户之前，请在您的 AWS 账户中创建一个用户迁移 Lambda 函数，并将该 Lambda 函数设置为您的用户池中的用户迁移触发器。向您的 Lambda 函数添加授权策略，该策略仅允许 Amazon Cognito 服务账户主体 `cognito-idp.amazonaws.com` 调用该 Lambda 函数，并且只能在您自己的用户池的上下文中进行。有关更多信息，请参阅[对 AWS Lambda 使用基于资源的策略（Lambda 函数策略）](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)。
**登录流程**
1. 用户打开您的应用程序并使用 Amazon Cognito 用户池 API 或通过托管登录进行登录。有关如何简化使用 Amazon Cogn APIs ito 登录的更多信息，请参阅。[将 Amazon Cognito 身份验证和授权与 Web 和移动应用程序集成](cognito-integrate-apps.md)
1. 您的应用程序将用户名和密码发送至 Amazon Cognito。如果您的应用程序具有使用 AWS SDK 构建的自定义登录界面，则您的应用程序必须使用[InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)或[AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html)与`USER_PASSWORD_AUTH`或`ADMIN_USER_PASSWORD_AUTH`流程。当您的应用使用其中一个流程时，开发工具包会将密码发送到服务器。
**注意**
在添加用户迁移触发器之前，请在您的应用程序客户端的设置中激活 `USER_PASSWORD_AUTH` 或 `ADMIN_USER_PASSWORD_AUTH` 流程。您必须使用这些流程而不是默认 `USER_SRP_AUTH` 流程。Amazon Cognito 必须向您的 Lambda 函数发送密码，以便它可以验证您的用户在另一个目录中的身份验证。SRP 会在您的 Lambda 函数中隐藏您用户的密码。
1. Amazon Cognito 检查提交的用户名是否与用户池中的用户名或别名匹配。您可以将用户的电子邮件地址、电话号码或首选用户名设置为用户池中的别名。如果用户不存在，Amazon Cognito 会将参数（包括用户名和密码）发送到您的 [迁移用户 Lambda 触发器](user-pool-lambda-migrate-user.md) 函数。
1. 您的 [迁移用户 Lambda 触发器](user-pool-lambda-migrate-user.md) 函数使用您的现有用户目录或用户数据库检查用户，或验证用户身份。该函数返回 Amazon Cognito 存储在用户池的用户配置文件中的用户属性。仅当提交的用户名与别名属性匹配时，您才能返回 `username` 参数。如果您希望用户继续使用其现有密码，您的函数将在 Lambda 响应中将属性 `finalUserStatus` 设置为 `CONFIRMED`。您的应用程序必须返回 [迁移用户 Lambda 触发器参数](user-pool-lambda-migrate-user.md#cognito-user-pools-lambda-trigger-syntax-user-migration) 中显示的所有 `"response"` 参数。
**重要**
不要在您的用户迁移 Lambda 代码中记录整个请求事件对象。此请求事件对象包括用户的密码。如果您不对日志进行消毒，则密码会显示在 CloudWatch 日志中。
1. Amazon Cognito 在您的用户池中创建用户配置文件，并将令牌返回您的应用程序客户端。
1. 您的应用程序执行令牌接收，接受用户身份验证，然后继续处理请求的内容。
迁移用户后，请使用 `USER_SRP_AUTH` 进行登录。安全远程密码 (SRP) 协议不会通过网络发送密码，并为您在迁移期间使用的 `USER_PASSWORD_AUTH` 流程提供安全优势。
如果迁移期间出现错误（包括客户端设备或网络问题），您的应用程序会从 Amazon Cognito 用户池 API 接收错误响应。发生这种情况时，Amazon Cognito 可能会也可能不会在您的用户池中创建用户账户。然后，用户应尝试再次登录。如果登录反复失败，请尝试在您的应用程序中使用忘记密码流程重置用户密码。
忘记密码流程还会使用 `UserMigration_ForgotPassword` 事件源调用您的 [迁移用户 Lambda 触发器](user-pool-lambda-migrate-user.md) 函数。由于用户在请求密码重置时没有提交密码，因此 Amazon Cognito 在发送到您的 Lambda 函数的事件中不包含密码。您的函数只能在现有用户目录中查找用户并返回属性，以添加到用户池中的用户配置文件中。在您的函数完成其调用并将其响应返回给 Amazon Cognito 后，您的用户池将通过电子邮件或 SMS 发送密码重置代码。在您的应用程序中，提示您的用户输入确认码和新密码，然后[ConfirmForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmForgotPassword.html)通过 API 请求将该信息发送给 Amazon Cognito。您还可以在托管登录中使用内置的忘记密码流程页面。
**其他资源**
+ [将用户迁移到 Amazon Cognito 用户池的方法](https://aws.amazon.com/blogs/security/approaches-for-migrating-users-to-amazon-cognito-user-pools/)
# 通过 CSV 文件将用户导入用户池中
如果您有外部身份存储，并且有时间为新的本地用户准备用户池，那么在迁移到 Amazon Cognito 用户池，选择从逗号分隔值（CSV）文件批量导入用户既省时省力，又可降低成本。CSV 文件导入是先下载和填入模板文件，然后在导入任务中将该文件移交给用户池的过程。您可以使用 CSV 导入来快速创建测试用户。您还可以通过编程的方式，使用读取 API 请求从外部身份存储中获取数据，然后解析这些数据的详细信息和属性，再将它们写入到文件中。
导入过程会设置所有用户属性的值，不过 **password** 除外。不支持导入密码，因为安全妥善做法要求密码不能为纯文本，而我们不支持导入哈希。这意味着，用户必须在首次登录时更改密码。使用此方法导入用户时，用户处于 `RESET_REQUIRED` 状态。
从 CSV 导入用户最省力的方法是在用户池中激活[无密码登录](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)。借助电子邮件地址和电话号码属性以及正确的用户池配置，用户可以在导入任务完成后立即使用电子邮件或短信一次性密码 (OTPs) 登录。有关更多信息，请参阅 [要求导入的用户重置密码](#cognito-user-pools-using-import-tool-password-reset)。
您也可以使用 [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API 请求，将 `Permanent` 参数设置为 `true` 来设置用户的密码。CSV 导入不会计入用户池中按月计费的活跃用户 (MAUs)。但是，确实会生成密码重置操作。 MAUs要在导入大量可能不会立即处于活动状态的带密码用户时控制成本，请将您的应用程序设置为在用户登录并收到 `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)
## 创建日 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 Logs 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\$1POOL\$1ID*是要将用户导入到的用户池的用户池标识符：
```
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\$1verified** 或 **phone\$1number\$1verified**
+ 每个用户至少有一个自动验证属性必须为 `true`。自动验证的属性是新用户加入您的用户池时，Amazon Cognito 自动向其发送验证码的电子邮件地址或电话号码。
+ 用户池必须至少有一个自动验证属性，要么是 **email\$1verified**，要么是 **phone\$1number\$1verified**。如果用户池没有自动验证属性，则导入任务不会启动。
+ 如果用户池只有一个自动验证属性，则该属性必须针对每个用户进行验证。例如，如果用户池只有 **phone\$1number** 为自动验证属性，则每个用户的 **phone\$1number\$1verified** 值都必须为 `true`。
**注意**
对于重置其密码的用户，用户必须拥有经过验证的电子邮件或电话号码。Amazon Cognito 将包含重置密码代码的消息发送到 CSV 文件中指定的电子邮件或电话号码。如果将消息发送到电话号码，则通过 SMS 消息发送。有关更多信息，请参阅 [在注册时验证联系人信息](signing-up-users-in-your-app.md#allowing-users-to-sign-up-and-confirm-themselves)。
+ **email**（如果 **email\$1verified** 为 `true`）
+ **phone\$1number**（如果 **phone\$1number\$1verified** 为 `true`）
+ 创建用户池时标记为必需的所有属性
+ 字符串式的属性值*不* 应该用引号括起来。
+ 如果属性值包含逗号，则您必须在逗号前使用反斜杠 (\$1)。这是因为 CSV 文件中的字段使用逗号分隔。
+ CSV 文件内容应采用不含字节顺序标记的 UTF-8 格式。
+ **cognito:username** 字段是必填项，并且在用户池中必须是唯一的。它可以是任何 Unicode 字符串。但是，它不能包含空格或制表符。
+ **出生日期**值（如果存在）必须采用以下格式**mm/dd/yyyy**。也就是说，如果生日日期为 1985 年 2 月 1 日，则必须编码为 **02/01/1985**。
+ **cognito:mfa\$1enabled** 字段必须符合用户池的 MFA 要求。如果您已将用户池设置为需要进行多重身份验证（MFA），则所有用户的此字段都必须为 `true` 或为空。如果您已将 MFA 设置为关闭，则所有用户的此字段都必须为 `false` 或为空。空值将导入的用户启用 MFA 的状态设置为用户池所需的状态。无论是否设置 `cognito:mfa_enabled` 值，您都可以在没有有效 MFA 因素的情况下将用户导入到要求 MFA 的用户池中。处于此状态的用户已激活 MFA，但在配置电子邮件属性、电话号码属性或 TOTP 之前无法登录，并且该配置是用户池中的有效 MFA 因素。
+ 最大长度为 16000 个字符。
+ CSV 文件的最大大小为 100MB。
+ 文件中的最大行（用户）数为 5,00000。此最大值不包括标题行。
+ **updated\$1at** 字段值应为纪元时间（用秒表示），例如：**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\$1NAME*是您为任务选择的名称，*USER\$1POOL\$1ID*是要向其中添加新用户的用户池的用户池 ID，*ROLE\$1ARN*也是您在中收到的角色 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\$1SIGNED\$1URL*返回的有效期为 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\$1POOL\$1ID*是您的用户池 ID，*JOB\$1ID*是您创建用户导入任务时返回的任务 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\$1SIGNED\$1URL*是您将 CSV 文件上传到的网址。*ROLE\$1ARN*是您在创建角色时收到的 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\$1TOKEN*字符串表示此列表命令还有其他结果。要列出更多结果，请使用 `--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\$1ID*/*JOB\$1NAME*。日志中的结果按行号引用用户。日志中不会写入用户数据。对于每个用户，都将出现类似于以下内容的行：
+ `[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. 您的应用程序重定向用户以进行登录。
# 使用用户属性
属性是各种条目的信息，用于帮助您标识单个用户，如名称、电子邮件和电话号码。新的用户池有一组默认*标准属性*。您也可以在中的用户池定义中添加自定义属性 AWS 管理控制台。本主题将详细介绍这些属性，并为您提供有关如何设置用户池的提示。
请勿将所有与用户相关的信息都应存储在属性中。例如，将频繁变化的用户数据（如使用情况统计数据或游戏分数）保存在单独的数据存储（如 Amazon Cognito Sync 或 Amazon DynamoDB）中。
在将输入的用户属性字符串值提交到用户池之前，请对其进行清理。分析提议的用户属性值的一种方法是使用 Lambda 触发器，例如[注册前](user-pool-lambda-pre-sign-up.md)。
**注意**
一些文档和标准将属性称为*成员*。
**Topics**
+ [标准属性](#cognito-user-pools-standard-attributes)
+ [用户名和首选用户名](#user-pool-settings-usernames)
+ [自定义登录属性](#user-pool-settings-aliases)
+ [自定义属性](#user-pool-settings-custom-attributes)
+ [属性权限和范围](#user-pool-settings-attribute-permissions-and-scopes)
## 标准属性
Amazon Cognito 根据 [OpenID Connect 规范](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)为所有用户分配一组标准属性。默认情况下，标准和自定义属性值可以是长度不超过 2048 个字符的任何字符串，但是某些属性值有格式限制。
标准属性是：
+ `name`
+ `family_name`
+ `given_name`
+ `middle_name`
+ `nickname`
+ `preferred_username`
+ `profile`
+ `picture`
+ `website`
+ `gender`
+ `birthdate`
+ `zoneinfo`
+ `locale`
+ `updated_at`
+ `address`
+ `email`
+ `phone_number`
+ `sub`
除 `sub` 外，默认情况下，对于所有用户，标准属性都是可选的。要将某个属性设置为必需属性，请在用户池创建过程中，选择属性旁边的 **Required**（必需）复选框。Amazon Cognito 为每个用户的 `sub` 属性分配一个唯一的用户标识符值。只能验证 **email** 和 **phone\$1number** 属性。
标准属性具有预定义的属性，您可以在 [DescribeUserPool API 响应](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPool.html#API_DescribeUserPool_ResponseSyntax)的`SchemaAttributes`参数中查看这些属性。您可以为这些属性设置自定义值，例如数据类型、可变性和长度限制。要修改标准属性属性，请在[CreateUserPool 架构参数](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html#CognitoUserPools-CreateUserPool-request-Schema)中设置其自定义值。您还可以在架构中设置必需的属性。在 Amazon Cognito 控制台中创建用户池时，您无法修改标准属性的属性。
**注意**
如果您将某个标准属性标记为 **Required**（必需），则用户必须为该属性提供一个值才能注册。要创建用户而不给出必填属性的值，管理员可以使用 [AdminCreateUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminCreateUser.html)API。创建用户池后，您无法在必需属性和非必需属性之间切换属性。标准属性详细信息和格式限制
**birthdate**
值必须是格式中有效的 10 个字符的日期 YYYY-MM-DD。
**电子邮件**
用户和管理员可以验证电子邮件地址值。
具有适当 AWS 账户 权限的管理员可以更改用户的电子邮件地址，也可以将其标记为已验证。使用 [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)API 或 [admin-update-user-attributes](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-update-user-attributes.html) AWS Command Line Interface (AWS CLI) 命令将电子邮件地址标记为已验证。使用此命令，管理员可以将 `email_verified` 属性更改为 `true`。您也可以在 Amazon Cognito 控制台的**用户**菜单中编辑用户，以将电子邮件地址标记为已验证。
值必须是[有效的电子邮件地址字符串](https://datatracker.ietf.org/doc/html/rfc3696#section-3)，遵循标准电子邮件格式，带有 @ 符号和域，长度不超过 2048 个字符。
**phone\$1number**
如果 SMS 多重验证 (MFA) 处于活动状态，用户必须提供电话号码。有关更多信息，请参阅 [向用户池添加 MFA](user-pool-settings-mfa.md)。
用户和管理员可以验证电话号码值。
具有适当 AWS 账户 权限的管理员可以更改用户的电话号码，也可以将其标记为已验证。使用 [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)API 或[admin-update-user-attributes](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/admin-update-user-attributes.html) AWS CLI 命令将电话号码标记为已验证。使用此命令，管理员可以将 `phone_number_verified` 属性更改为 `true`。您也可以在 Amazon Cognito 控制台的**用户**菜单中编辑用户，以将电话号码标记为已验证。
电话号码必须遵循以下格式规则：电话号码必须以加号 (**\$1**) 开头，后面紧跟国家/地区代码。电话号码只能包含 **\$1** 号和数字。先删除电话号码中的任何其他字符，如圆括号、空格或短划线 (**-**)，然后再将该值提交给服务。例如，美国境内的电话号码必须遵循以下格式：**\$114325551212**。
**preferred\$1username**
您可以将 `preferred_username` 选择为必需或别名，但不能同时选择这两者。如果`preferred_username`是别名，则可以向 [UpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html)API 操作发出请求，并在确认用户后添加属性值。
**sub**
根据 `sub` 属性对用户编制索引和进行搜索。`sub` 属性是每个用户池中的唯一用户标识符。用户可以更改如 `phone_number` 和 `email` 等属性。`sub` 属性具有固定的值。有关查找用户的更多信息，请参阅[管理和搜索用户账户](how-to-manage-user-accounts.md)。
### 查看必需属性
通过以下过程可查看给定用户池的必需属性。
**注意**
在创建用户池后，您无法更改必需属性。
**查看必需属性**
1. 前往 [Amazon Cognito](https://console.aws.amazon.com/cognito/home) AWS 管理控制台如果控制台提示您，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**注册**菜单。
1. 在 **Required attributes**（必需属性）部分中，查看用户池的必需属性。
## 用户名和首选用户名
`username` 值是一个单独的属性，与 `name` 属性不同。每个用户都有 `username` 属性。Amazon Cognito 会自动为联合用户生成用户名。您必须提供 `username` 属性以在 Amazon Cognito 目录中创建本地用户。创建用户后，您将无法更改 `username` 属性的值。
开发人员可以使用 `preferred_username` 属性为用户提供一个他们可以更改的用户名。有关更多信息，请参阅 [自定义登录属性](#user-pool-settings-aliases)。
如果您的应用程序不需要用户名，就不必要求用户提供用户名。您的应用程序可以在后台为用户创建唯一的用户名。如果您希望用户使用电子邮件地址和密码注册和登录，这非常有用。有关更多信息，请参阅 [自定义登录属性](#user-pool-settings-aliases)。
在用户池中，`username` 必须是唯一的。`username` 可重复使用，但只能是在您已将其删除且不再使用它的情况下。有关属性的字符串限制的信息，请参阅 [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Username)API 请求的*用户名`username`*属性。
## 自定义登录属性
创建用户池时，如果您希望用户能够使用电子邮件地址或电话号码作为其用户名进行注册和登录，则可以设置*用户名属性*。或者，您可以设置*别名属性*为用户提供选项：用户可以在注册时包含多个属性，然后使用用户名、首选用户名、电子邮件地址或电话号码登录。
**重要**
创建用户池后，您无法更改此设置。
### 如何在别名属性和用户名属性之间进行选择
| 您的要求 | 别名属性 | 用户名属性 |
| --- |--- |--- |
| 用户有多个登录属性 | 是¹ | No² |
| 用户必须先验证电子邮件地址或电话号码，然后才能使用该地址或电话号码登录 | 是 | 否 |
| 使用重复的电子邮件地址或电话号码注册用户并防止出现UsernameExistsException错误³ | 是 | 否 |
| 可以将相同的电子邮件地址或电话号码属性值分配给多个用户 | 是⁴ | 否 |
¹ 可用的登录属性包括用户名、电子邮件地址、电话号码和首选用户名。
² 可以使用电子邮件地址或电话号码进行登录。
³ 当用户使用可能重复的电子邮件地址或电话号码注册但没有用户名时，您的用户池不会生成 `UsernameExistsException` 错误。此行为独立于**防止用户名存在错误**，此错误适用于登录操作，但不适用于注册操作。
⁴ 只有最后验证了该属性的用户才能使用该属性登录。
#### 选项 1：多个登录属性（别名属性）
当用户有用户名但也可以使用某个属性登录时，该属性便是*别名*。如果您想允许用户在登录表单的用户名字段中在其用户名和其他属性值之间进行选择，则可以设置别名。`username` 属性是一个固定值，用户无法更改。如果您将某个属性标记为别名，用户就可以使用该属性代替用户名来登录。您可以将电子邮件地址、电话号码和首选用户名属性标记为别名。例如，如果您选择电子邮件地址和电话号码作为用户池的别名，该用户池中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。
要选择别名属性，请在创建用户池时选择 **User Name**（用户名）和至少一个其他登录选项。
**注意**
将用户池配置为不区分大小写时，用户可以使用小写或大写字母进行注册或使用别名登录。有关更多信息，请参阅 *Amazon Cognito 用户池 API* 参考[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)中的。
如果您选择电子邮件地址作为别名，Amazon Cognito 不接受与有效电子邮件地址格式匹配的用户名。同样，如果您选择电话号码作为别名，Amazon Cognito 将不接受与有效的电话号码格式相匹配的用户池的用户名。
**注意**
在用户池中，别名值必须是唯一的。如果您为电子邮件地址或电话号码配置别名，那么提供的值只能在一个账户中处于已验证状态。在注册期间，如果您的用户提供电子邮件地址或电话号码作为别名值，而另一用户已使用该别名值，注册将成功。然而，当用户尝试使用此电子邮件（或电话号码）确认账户并输入有效的代码时，Amazon Cognito 会返回 `AliasExistsException` 错误。该错误向用户指出，已存在使用此电子邮件地址（或电话号码）的账户。此时，用户可以放弃新账户的创建，并尝试重置旧账户的密码。如果用户继续创建新账户，您的应用程序必须使用 `forceAliasCreation` 选项调用 `ConfirmSignUp` API。`ConfirmSignUp` 和 `forceAliasCreation` 结合会将别名从以前的账户移至新创建的账户，并在以前的账户中将此属性标记为未经验证。
只有在您的用户验证电话号码和电子邮件地址后，电话号码和电子邮件地址才会成为用户的活动别名。如果您将电子邮件地址和电话号码用作别名，建议您选择对其进行自动验证。
选择别名属性以防止用户注册时出现电子邮件地址和电话号码属性的 `UsernameExistsException` 错误。
激活 `preferred_username` 属性，以便您的用户可以更改他们用来登录的用户名，而他们的 `username` 属性值不会更改。如果您想设置这种用户体验，请提交新的 `username` 值作为 `preferred_username`，并选择 `preferred_username` 作为别名。这样，用户就可以使用输入的新值登录。如果选择 `preferred_username` 作为别名，您的用户只有在确认账户时才能提供该值。他们在注册期间无法提供该值。
当用户使用用户名注册时，您可以选择他们是否可以使用以下一个或多个别名登录。
+ 经过验证的电子邮件地址
+ 经过验证的电话号码
+ 首选用户名
用户注册后可以更改这些别名。
**重要**
当您的用户池支持使用别名登录，并且您想要向用户授权或查找用户时，请不要通过用户的任何登录属性来识别您的用户。固定值的用户标识符 `sub` 是用户身份的唯一一致指标。
在创建用户池时包括以下步骤，以便用户可以使用别名登录。
------
#### [ Phone number or email address (console) ]
您必须在创建用户池时将电子邮件地址和电话号码设置为别名属性。
**在 Amazon Cognito 控制台中创建带有用户名别名的用户池**
1. 转到 AWS 管理控制台中的 [Amazon Cognito](https://console.aws.amazon.com/cognito/home)。如果控制台提示您，请输入您的 AWS 凭据。
1. 使用**开始使用**或**创建用户池**按钮创建新的用户池。
1. 在**定义您的应用程序**中选择应用程序设置。
1. 在**配置选项**中的**登录标识符的选项**下，选中**用户名**旁边的复选框以及至少一个其他选项，即**电子邮件**和**电话号码**。
1. 选择您的别名属性作为**注册的必要属性**。在托管登录的注册表单中，Amazon Cognito 会提示新用户为必要属性提供值。
1. 在**添加返回 URL** 下，设置应用程序回调 URL，以便在托管登录的登录后进行重定向。
1. 选择**创建**。
------
#### [ Phone number or email address (API/SDK) ]
使用 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)API 操作创建新的用户池。如下所示配置 `AliasAttributes` 参数。如果您只需要电话号码别名，则可以删除 `email` 条目；如果您只需要电子邮件地址别名，则可以删除 `phone_number` 条目。
```
"AliasAttributes": [
"email",
"phone_number"
],
```
------
#### [ Preferred username (API/SDK) ]
Amazon Cognito 控制台创建不使用 `preferred_username` 作为别名的用户池。要使用`preferred_username`别名创建用户池，请在 AWS SDK 中设置包含 [CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)API 请求的用户池。要支持在注册时创建首选用户名属性，请将 `preferred_username` 设置为必需属性。在托管登录的注册表单中，Amazon Cognito 会提示新用户为必要属性提供值。您*可以*在 Amazon Cognito 控制台中将 `preferred_username` 设置为必需属性，但这并不能将其用作别名。
**配置为别名**
如下所示，在 `CreateUserPool` 请求的 `AliasAttributes` 参数中将 `preferred_username` 配置为别名。从列表中删除任何您不想作为别名属性的值。
```
"AliasAttributes": [
"email",
"phone_number",
"preferred_username"
],
```
**根据需要进行配置**
在托管登录的注册表单中，Amazon Cognito 会提示新用户为必要属性提供值。`preferred_username`根据需要在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)请求的`SchemaAttributes`参数中进行配置。
要将首选用户名设置为必需属性，请按如下所示进行配置。以下示例修改 `preferred_username` 的默认方案，以根据需要对其进行设置。诸如 `AttributeDataType`（默认为 `string`）和 `StringAttributeConstraints`（长度默认为 1-99 个字符）等其他方案参数采用默认值。
```
"Schema": [
{
"Name": "preferred_username",
"Required": true
}
]
```
------
#### 选项 2：将电子邮件地址或电话号码作为登录属性（用户名属性）
当用户使用电子邮件地址或电话号码作为其用户名进行注册时，您可以选择他们是否可以仅使用电子邮件地址、仅使用电话号码或其中之一进行注册。
要选择用户名属性，请在创建用户池时不要选择**用户名**作为登录选项。
电子邮件地址或电话号码必须是唯一的，并且不能已被其他用户使用。它不必经过验证。用户使用电子邮件地址或电话号码注册之后，将无法使用相同的电子邮件地址或电话号码创建新账户。如果需要，用户只能重复使用现有账户并重置账户的密码。但是，用户可以将电子邮件地址或电话号码更改为新的电子邮件地址或电话号码。如果电子邮件地址或电话号码未被使用，它将成为新的用户名。
当您同时选择电子邮件地址和电话号码作为用户名属性时，用户可以使用其中一个属性登录，即使他们为这两个属性都提供了值。登录用户名基于您在`Username`参数中传递的[SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html#CognitoUserPools-SignUp-request-Username)值。
**注意**
如果用户使用电子邮件地址作为用户名进行注册，则可以将用户名更改为另一个电子邮件地址，但他们无法将用户名更改为电话号码。如果用户使用电话号码进行注册，他们可以将用户名更改为另一个电话号码，但他们无法将用户名更改为电子邮件地址。
在用户池创建过程中使用以下步骤设置使用电子邮件地址或电话号码注册和登录。
------
#### [ Username attributes (console) ]
以下过程创建带有电子邮件地址或电话号码用户名属性的用户池。在 Amazon Cognito 控制台中设置用户名属性的过程的不同之处在于，您不必同时将**用户名**设置为登录属性。
**在 Amazon Cognito 控制台中创建带有用户名属性的用户池**
1. 转到 AWS 管理控制台中的 [Amazon Cognito](https://console.aws.amazon.com/cognito/home)。如果控制台提示您，请输入您的 AWS 凭据。
1. 使用**开始使用**或**创建用户池**按钮创建新的用户池。
1. 在**定义您的应用程序**中选择应用程序设置。
1. 在**配置选项**中的**登录标识符的选项**下，选择您的用户名属性：**电子邮件**、**电话号码**或同时选择两者。取消选中**用户名**。
1. 作为最佳实践，请选择用户名属性作为**注册的必要属性**。在托管登录的注册表单中，Amazon Cognito 会提示新用户为必要属性提供值。如果您未按要求设置用户名属性，Amazon Cognito 不会提示新用户为其提供值。在这种情况下，您必须将应用程序配置为收集并提交每个用户的电子邮件地址或电话号码，然后他们才能登录。
1. 在**添加返回 URL** 下，设置应用程序回调 URL，以便在托管登录的登录后进行重定向。
1. 选择**创建**。
------
#### [ Username attributes (API/SDK) ]
在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)请求中，如图所示配置`UsernameAttributes`参数。要仅允许使用电子邮件地址用户名登录，请在此列表中单独指定 `email`。要仅允许使用电话号码用户名登录，请单独指定 `phone_number`。此参数将覆盖用户名作为登录选项。
```
"UsernameAttributes": [
"email",
"phone_number"
],
```
------
配置用户名属性时，可以发出 [SignUp](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignUp.html)API 请求，在`username`参数中传递电子邮件地址或电话号码。以下是带有用户名属性的代码 `SignUp` API 操作的行为。
+ 如果 `username` 字符串采用有效的电子邮件地址格式，例如 `user@example.com`，用户池将使用 `username` 值自动填充用户的 `email` 属性。
+ 如果 `username` 字符串采用有效的电话号码格式，例如 `+12065551212`，用户池将使用 `username` 值自动填充用户的 `phone_number` 属性。
+ 如果 `username` 字符串格式不是电子邮件或电话号码格式，`SignUp` API 将返回异常。
+ 如果 `username` 字符串包含已被使用的电子邮件地址或电话号码，`SignUp` API 将返回异常。
+ `SignUp` API 使用您的用户的 [UUID](cognito-terms.md#terms-uuid) 填充 `username` 属性。此 UUID 与用户身份令牌中的 `sub` 声明具有相同的值。
APIs除了操作之外，您还可以在所有[ListUsers](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUsers.html)操作中使用电子邮件地址或电话号码代替用户名。在 `ListUsers` API 请求中，您可以指定 `email` 或 `phone_number` 的 `Filter`。如果按 `username` 进行筛选，则必须提供 UUID 用户名，而不是电子邮件地址或电话号码。
## 自定义属性
您可以将最多 50 个自定义属性添加到您的用户池。您可以为自定义属性指定一个最小和/或最大长度。但是，任何自定义属性的最大长度不能超过 2048 个字符。自定义属性的名称必须与`Name`参数中描述的正则表达式模式相匹配[SchemaAttributeType](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SchemaAttributeType.html)。
**每个自定义属性都具有以下特性：**
+ 可以将其定义为字符串、数字、布尔值或 `DateTime` 对象。Amazon Cognito 仅将自定义属性值作为字符串写入 ID 令牌。
**注意**
在 Amazon Cognito 控制台中，您只能添加字符串和数字数据类型的自定义属性。布尔值和`DateTime`属性数据类型等其他选项仅在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)和 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html)API 请求的`SchemaAttributes`属性中可用。
+ 您不能要求用户为属性提供值。
+ 将其添加到用户池后，您将无法删除或更改它。
+ 属性名称的字符长度在 Amazon Cognito 接受的限制范围内。有关更多信息，请参阅 [Amazon Cognito 中的限额](quotas.md)。
+ 它可能是*可以改变的*，也可能是*不可改变的*。在创建用户时，您只能将值写入不可改变属性。如果您的应用程序客户端具有该属性的写入权限，您可以更改可变属性的值。请参阅[属性权限和范围](#user-pool-settings-attribute-permissions-and-scopes)了解更多信息。
**注意**
在您的代码和 [使用基于角色的访问控制](role-based-access-control.md) 的规则设置中，自定义属性需要使用 `custom:` 前缀，以便将它们与标准属性区分开来。
在创建用户池时，您还可以在的*属性中添加开发者属性[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html)*。`SchemaAttributes`开发人员属性具有 `dev:` 前缀。您只能使用 AWS 凭证修改用户的开发者属性。开发人员属性是一项旧版特征，Amazon Cognito 已将其替换为应用程序客户端读写权限。
通过以下过程创建新的自定义属性。
**使用控制台添加自定义属性**
1. 前往 [Amazon Cognito](https://console.aws.amazon.com/cognito/home) AWS 管理控制台如果控制台提示您，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**注册**菜单，然后在**自定义属性**部分，选择**添加自定义属性**。
1. 在存储库的 **Add custom attributes**（添加自定义属性）页面上，提供有关新属性的以下详细信息：
+ 输入 **Name**（名称）。
+ 选择 **Type**（类型）（**字符串**或**数字**）。
+ 输入**最小**字符串长度或数字值。
+ 输入**最大**字符串长度或数字值。
+ 如果您想授予用户在设置初始值后更改自定义属性值的权限，请选择 **Mutable**（可变）。
1. 选择 **Save changes**（保存更改）。
## 属性权限和范围
对于每个应用程序客户端，您可以为每个用户属性设置读取和写入权限。这样，您可以控制为了读取和修改您为用户存储的每个属性，任何应用程序所具有的访问权限。例如，您可以设置一个自定义属性，用于指明用户是否为付费客户。您的应用程序可能能够看到此属性，但无法直接更改它。相反，您可以使用管理工具或后台进程更新此属性。您可以通过 Amazon Cognito 控制台、Amazon Cognito API 或 AWS CLI设置用户属性的权限。默认情况下，任何新的自定义属性都不可用，直到您为其设置读取和写入权限。默认情况下，创建新的应用程序客户端时，您将授予应用程序对所有标准和自定义属性的读取和写入权限。要将应用程序限制为仅使用它所需的信息量，请在应用程序客户端配置中为属性分配特定权限。
妥善做法是在创建应用程序客户端时指定属性的读取和写入权限。向您的应用程序客户端授予应用程序运行所需的最小用户属性集的访问权限。
**注意**
[DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html)只有在配置默认权限之外的应用程序客户端权限`WriteAttributes`时，才会返回`ReadAttributes`和的值。
**更新属性权限（AWS 管理控制台）**
1. 前往 [Amazon Cognito](https://console.aws.amazon.com/cognito/home) AWS 管理控制台如果控制台提示您，请输入您的 AWS 凭据。
1. 选择 **User Pools**（用户池）。
1. 从列表中选择现有用户池。
1. 选择**应用程序客户端**菜单，然后从列表中选择应用程序客户端。
1. 在**属性权限**选项卡中，选择**编辑**。
1. 在 **Edit attribute read and write permissions**（编辑设置属性读取和写入权限）页面上，配置读取和写入权限，然后选择 **Save changes**（保存更改）。
使用自定义属性对每个应用程序客户端重复这些步骤。
对于每个应用程序客户端，您可以将属性标记为可读或可写。这对于标准属性和自定义属性均适用。您的应用程序可以检索您标记为可读的属性的值，也可以设置或修改您标记为可写的属性的值。如果您的应用程序尝试为其无权写入的属性设置值，Amazon Cognito 会返回。`NotAuthorizedException` [GetUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html)请求包括带有应用程序客户端声明的访问令牌；Amazon Cognito 仅返回应用程序客户端可以读取的属性的值。来自应用程序的用户 ID 令牌仅包含与可读属性相对应的声明。所有应用程序客户端都可以写入用户池所需的属性。仅当您还为尚未具有值的必需属性提供值时，才能在 Amazon Cognito 用户池 API 请求中设置相应属性的值。
自定义属性具有不同的读写权限特征。您可以将它们创建为用户池的可变或不可变属性，并可以将它们设置为任何应用程序客户端的读或写属性。
在创建用户期间，不可变的自定义属性可以更新一次。您可以使用以下方法填充不可变的属性。
+ `SignUp`：用户注册了一个应用程序客户端，该客户端具有对不可变自定义属性的写访问权限。它们为该属性提供了一个值。
+ 使用第三方 IdP 登录：用户登录到一个应用程序客户端，该客户端具有对不可变自定义属性的写访问权限。IdP 的用户池配置有一条规则，可以将提供的声明映射到不可变的属性。这可以实现，但不太实际，因为用户只能登录一次。在首次登录后，如果用户尝试再次登录，Amazon Cognito 会因为映射规则指向一个现在不可写的属性而拒绝登录尝试。
+ `AdminCreateUser`：您为不可变属性提供一个值。
### 使用范围的属性权限
在使用 AWS SDK 或 CDK、REST API 或配置的用户池中 AWS CLI，您可以使用 OIDC 范围配置应用程序客户端的读取或写入权限。`oidc:profile``oidc:profile` 授予对以下标准属性的读取或写入权限：
+ `name`
+ `family_name`
+ `given_name`
+ `middle_name`
+ `nickname`
+ `preferred_username`
+ `profile`
+ `picture`
+ `website`
+ `gender`
+ `birthdate`
+ `zoneinfo`
+ `locale`
此列表是 OIDC 标准属性减去 `email`、`phone_number`、`sub` 和 `address`，如 [OIDC 规范第 2.4 节](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes)中所定义。有关您可以分配给应用程序客户端的范围的信息，请参阅[作用域、M2M 和资源服务器](cognito-user-pools-define-resource-servers.md)。
要将您的应用程序客户端配置为写入`oidc:profile`作用域下的属性，请在[CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html)或 [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html)API 请求中[WriteAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html#CognitoUserPools-CreateUserPoolClient-request-WriteAttributes)将`oidc:profile`的值设置为，以及您希望允许应用程序修改的任何其他属性。同样，要授予对这些属性的读取权限，`oidc:profile`请添加的值[ReadAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html#CognitoUserPools-CreateUserPoolClient-request-ReadAttributes)。
您可以在创建用户池后更改属性权限和范围。