用户池属性 - Amazon Cognito

Amazon Cognito 根据 OpenID Connect 规范为所有用户分配了以下组标准属性。

address
birthdate
email
family_name
gender
given_name
locale
middle_name
name
nickname
phone_number
picture
preferred_username
profile
updated_at
website
zoneinfo

这些属性作为所有用户的可选属性提供。要将某个属性设置为必需属性，请在用户池创建过程中，选择属性旁边的 Required（必需）复选框。

注意

如果某个标准属性被标记为 Required（必需），则用户必须为该属性提供一个值才能注册。通过使用 AdminCreateUser API，管理员无需为必需属性提供值就可以创建用户。在用户池创建完成后，属性就不能在必需与非必需之间切换。

默认情况下，标准和自定义属性值可以是任何不超过 2048 个字符的字符串，但是某些属性值（例如 updated_at）有格式限制。只能验证电子邮件和电话。

注意

在此规范中，属性称为成员。

以下是有关上述某些字段的一些附加说明。

email

电子邮件地址值可以进行验证。

具有适当Amazon账户权限的管理员可以更改用户的电子邮件，并将其标记为已验证。这一操作可通过使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes CLI 命令将 email_verified 属性更改为 true 来完成。

phone

如果启用了 SMS 多重验证 (MFA)，则电话号码为必需属性。有关更多信息，请参阅向用户池添加 MFA。

电话号码值可以进行验证。

具有适当Amazon账户权限的管理员可以更改用户的电话号码，并将其标记为已验证。这一操作可通过使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes CLI 命令将 phone_number_verified 属性更改为 true 来完成。

重要

电话号码必须遵循以下格式规则：电话号码必须以加号 (+) 开头，后面紧跟国家/地区代码。电话号码只能包含 + 号和数字。您必须先删除电话号码中的任何其他字符，如圆括号、空格或短划线 (-)，然后才能将该值提交给服务。例如，美国境内的电话号码必须遵循以下格式：+14325551212。

preferred_username

不能同时将 preferred_username 选为必需属性和别名。如果 preferred_username 是一个别名，用户可以通过使用 UpdateUserAttributes API 进行确认后再添加属性值。

查看必需属性

通过以下过程可查看给定用户池的必需属性。

注意

在用户池创建完成后，您无法更改必需属性。

username 值是一个单独的属性，与 name 属性不同。在注册用户时，username 始终为必需项，并且在用户创建后无法更改。

开发人员可以使用 preferred_username 属性让用户设置一个可以更改的用户名。有关更多信息，请参阅 Aliases。

如果您的应用程序不需要用户名，就不必要求用户提供用户名。您的应用程序可以在后台为用户创建唯一的用户名。这非常有用，例如，当您希望用户使用电子邮件地址和密码注册和登录时。有关更多信息，请参阅 Aliases。

在用户池中，username 必须是唯一的。username 可重复使用，但只能是在已删除且不再使用的情况下。

您可以允许最终用户通过使用别名使用多个标识符登录。默认情况下，用户使用他们的用户名和密码登录。用户名是一个固定值，用户无法更改。如果您将某个属性标记为别名，用户就可以使用该属性代替用户名来登录。电子邮件地址、电话号码和首选用户名属性都可以标记为别名。例如，如果电子邮件和电话被选为用户池的别名，该用户池中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。

注意

当您将用户池配置为不区分用户名大小写时，您可以选择在别名中使用小写或大写字母登录或注册。有关更多信息，请参阅《Amazon Cognito 用户池 API 参考》中的 CreateUserPool。

如果电子邮件被选为别名，用户名将无法匹配有效的电子邮件格式。同样，如果电话号码被选为别名，该用户池的服务将不接受与有效的电话号码模式相匹配的用户名。

注意

在用户池中，别名值必须是唯一的。如果为电子邮件地址或电话号码配置了别名，那么提供的值只能在一个账户中处于已验证状态。在注册期间，如果电子邮件地址或电话号码从一个已被使用的其他账户中作为别名提供，注册会成功。然而，当用户尝试使用此电子邮件（或电话号码）确认账户并输入有效的代码时，会出现 AliasExistsException 错误。该错误向用户指出，已存在使用此电子邮件 (或电话号码) 的账户。此时，用户可以放弃新账户的创建，然后尝试重置旧账户的密码。如果用户继续创建新账户，您的应用程序应使用 ConfirmSignUp 选项调用 forceAliasCreation API。这会将别名从以前的账户移至新创建的账户，还会将该属性在以前的账户中标记为未经验证。

电话号码和电子邮件地址只有经过验证之后才能成为用户的有效别名。因此，如果您将电子邮件地址和电话号码用作别名，我们建议您选择对其进行自动验证。使用 preferred_username 属性，用户便可拥有更改用户名的体验，但实际上用户的实际用户名值不可更改。

如果您想实现这种用户体验，请提交新的 username 值作为 preferred_username，并选择 preferred_username 作为别名。这样，用户就可以使用输入的新值登录。如果选择 preferred_username 作为别名，只有在确认账户后才能提供该值。在注册期间无法提供该值。

使用别名简化用户注册和登录

在用户池创建过程中，您可以选择是否允许用户使用电子邮件地址或电话号码作为其用户名注册。

注意

在用户池创建完成后，您无法更改此设置。

在这种情况下，用户使用用户名注册。此外，您可以选择性地允许用户使用以下一个或多个别名登录：

经过验证的电子邮件地址
经过验证的电话号码
首选的用户名

用户注册后可以更改这些别名。

在用户池创建过程中通过以下步骤，以允许使用别名登录。

Original console

配置用户池使用别名登录

转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 Manage User Pools (管理用户池)。
在页面右上角，选择 Create a user pool (创建用户池)。
在页面左上角，选择 Review（查看）。
在 How do you want your end users to sign-in?（您希望您的终端用户如何登录？）下的 Attributes（属性）选项卡中，选择 Username（用户名），然后选择下列选项之一：
- Also allow sign in with verified email address（还允许使用经验证的电子邮件地址登录）：此选项允许用户使用其电子邮件地址登录。
- Also allow sign in with verified phone number（还允许使用经验证的电话号码登录）：此选项允许用户使用其电话号码登录。
- Also allow sign in with preferred username（还允许使用首选用户名登录）：此选项允许用户使用首选的用户名登录。用户可以更改此用户名。
选择 Next step（下一步）保存，然后完成向导中的所有步骤。

New console

使用首选用户名配置用户池

转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 User Pools（用户池）。
在页面右上角，选择 Create a user pool（创建用户池）以开启用户池创建向导。
在 Configure sign-in experience（配置登录体验）中，选择您想将其与用户池关联的身份 Provider types（提供商类型）。
在 Cognito user pool sign-in options（Cognito 用户池登录选项）下，选择 User name（用户名）、Email（电子邮件）和 Phone number（电话号码）的任意组合。
在 User name requirements（用户名要求）下，选择 Allow users to sign in with a preferred user name（允许用户使用首选用户名登录），即可允许用户设置登录时要使用的备用用户名。
选择 Next（下一步），然后完成向导中的所有步骤。

在这种情况下，用户使用电子邮件地址或电话号码作为其用户名注册。您可以选择是否允许仅使用电子邮件地址、仅使用电话号码或使用任意一项进行注册。

电子邮件或电话号码必须是唯一的，并且不能已被其他用户使用。它不必经过验证。用户使用电子邮件或电话号码注册之后，将无法使用相同的电子邮件或电话号码创建新账户。如果需要，用户只能重复使用现有账户并重置账户的密码。但是，用户可以将电子邮件或电话号码更改为新的电子邮件或电话号码；如果电子邮件或电话号码未被使用，它将成为新的用户名。

注意

如果用户使用电子邮件地址作为用户名注册，则可以将用户名更改为另一个电子邮件地址；他们无法将用户名更改为电话号码。如果用户使用电话号码注册，他们可以将用户名更改为另一个电话号码；他们无法将用户名更改为电子邮件地址。

在用户池创建过程中通过以下步骤，以允许使用电子邮件或电话号码注册和登录。

Original console

配置用户池使用电子邮件或电话号码注册和登录

转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 Manage User Pools (管理用户池)。
在页面右上角，选择 Create a user pool (创建用户池)。
在页面左上角，选择 Review（查看）。
在 How do you want your end users to sign-in?（您希望您的终端用户如何登录？）下的 Attributes（属性）选项卡中，选择 Email address or phone number（电子邮件地址或电话号码），然后选择下列选项之一：
- Allow email addresses（允许使用电子邮件地址）：允许用户使用电子邮件作为用户名注册。
- Allow phone numbers（允许使用电话号码）：允许用户使用电话号码作为用户名注册。
- Allow both email addresses and phone number (users can choose one)（允许同时使用电子邮件地址和电话号码（用户可选择其中一个））：允许用户在注册过程中使用电子邮件地址或电话号码作为用户名。
选择 Next step（下一步）保存，然后完成向导中的所有步骤。

New console

配置用户池使用电子邮件或电话号码注册和登录

转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 User Pools（用户池）。
在页面右上角，选择 Create a user pool（创建用户池）以开启用户池创建向导。
在 Cognito user pool sign-in options（Cognito 用户池登录选项）下，选择 User name（用户名）、Email（电子邮件）和 Phone number（电话号码）的任意组合，表示您希望允许用于登录的别名属性。
在 User name requirements（用户名要求）下，选择下列一个或两个选项：
- Allow users to sign in with a preferred user name（允许用户使用首选用户名登录）：允许用户使用首选用户名登录。用户可以更改此用户名。
- Make user name case sensitive（设置用户名区分大小写）：将用户名设置为区分大小写，其中 ExampleUser 和 exampleuser 是唯一的用户名。
选择 Next（下一步），然后完成向导中的所有步骤。

注意

您不需要将电子邮件或电话号码标记为用户池的必需属性。

在应用程序中实施选项 2

调用 CreateUserPool API，以创建用户池。将 UserNameAttributes 参数设置为 phone_number、email 或 phone_number | email。
调用 SignUp API 并在 API 的 username 参数中传递电子邮件地址或电话号码。此 API 可执行以下操作：
- 如果 username 字符串采用有效的电子邮件格式，用户池将使用 email 值自动填充用户的 username 属性。
- 如果 username 字符串采用有效的电话号码格式，用户池将使用 phone_number 值自动填充用户的 username 属性。
- 如果 username 字符串格式不是电子邮件或电话号码格式，SignUp API 将出现异常。
- SignUp API 为用户生成一个持久性 UUID，并将其作为内部不可变的用户名属性。此 UUID 与用户身份令牌中的 sub 声明具有相同的值。
- 如果 username 字符串包含已被使用的电子邮件地址或电话号码，SignUp API 将引发异常。

您可以使用电子邮件地址或电话号码作为别名，在除 ListUsers API 之外的所有 API 中代替用户名。当您调用 ListUsers 时，您可以按 email 或 phone_number 属性搜索；如果您按 username 搜索，则必须提供实际的用户名，而不是别名。

您可以将最多 50 个自定义属性添加到您的用户池。您可以为自定义属性指定一个最小和/或最大长度。但是，任何自定义属性的最大长度不能超过 2048 个字符。

每个自定义属性：

可以定义为一个字符串或数字。
不能是必需的。
一旦添加到用户池，就不能删除或更改。
可以有一个名称，且此名称的字符长度符合 Amazon Cognito 接受的限制。有关更多信息，请参阅 Amazon Cognito 中的配额。

注意

在您的代码和基于角色的访问控制的规则设置中，自定义属性需要使用 custom: 前缀，以便将它们与标准属性区分开来。

通过以下过程创建新的自定义属性。

Original console

使用控制台添加自定义属性

在 https://console.amazonaws.cn/cognito 打开 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 Manage User Pools (管理用户池)。
在 Your User Pools (您的用户池) 页面上，选择要配置的用户池。
在左侧的导航栏中，选择属性。
在 Do you want to add custom attributes?（是否要添加自定义属性）下，选择 Add custom attribute（添加自定义属性）。
提供有关新属性的以下详细信息：
- 选择数据 Type（类型）（字符串或数字）
- 输入 Name（名称）值。
- 输入 Min length（最小长度）值
- 输入 Max length（最大长度）值
- 如果您想让用户能够在为自定义属性提供值后更改该值，请选择 Mutable（可变）。
选择保存更改。

New console

使用控制台添加自定义属性

转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。
选择 User Pools（用户池）。
从列表中选择现有用户池。
选择 Sign-up experience（注册体验）选项卡，然后在 Custom attributes（自定义属性）部分，选择 Add custom attributes（添加自定义属性）。
在存储库的 Add custom attributes（添加自定义属性）页面上，提供有关新属性的以下详细信息：
- 输入 Name（名称）值。
- 选择 Type（类型）（字符串或数字）
- 输入 Min（最小）长度值
- 输入 Max（最大）长度值
- 如果您想让用户能够在为自定义属性提供值后更改该值，请选择 Mutable（可变）。
选择保存更改。

您可以为每个应用程序的每个用户属性设置读取和写入权限。这使您能够控制哪些应用程序可以对存储的每个用户属性进行查看和修改。例如，您可以设置一个自定义属性，用于指明用户是否为付费客户。您的应用程序可以查看此属性，但无法直接修改。相反，您可以使用管理工具或后台进程更新此属性。可以通过 Amazon Cognito 控制台、API 或 Amazon CLI 设置用户属性的权限。默认情况下，任何新的自定义属性都不可用，直到您为其设置读取和写入权限。

使用自定义属性对每个应用程序客户端重复这些步骤。

可以针对每个应用程序将属性标记为可读或可写。这对于标准属性和自定义属性均适用。应用程序可以读取标记为可读的属性，也可以编写标记为可写的属性。如果应用程序尝试更新不可写的属性，就会收到 NotAuthorizedException 异常。当应用程序调用 GetUser 时，只能收到该应用程序可读的属性。经过身份验证后发出的 ID 令牌仅包含与可读属性相对应的声明。用户池中的必需属性始终为可写属性。如果您使用 Amazon CLI 或管理 API 来设置可写属性但不提供必需属性，就会出现 InvalidParameterException 异常。

您可以在创建用户池后更改属性权限和范围。