用户池属性
属性是各种条目的信息，用于帮助您标识单个用户，如名称、电子邮件和电话号码。新的用户池有一组默认标准属性。您也可以在 Amazon Web Services Management Console 中为您的用户池定义添加自定义属性。本主题将详细介绍这些属性，并为您提供有关如何设置用户池的提示。
请勿将所有与用户相关的信息都应存储在属性中。例如，将频繁变化的用户数据（如使用情况统计数据或游戏分数）保存在单独的数据存储（如 Amazon Cognito Sync 或 Amazon DynamoDB）中。
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（电子邮件）和 phone（电话）。
注意
一些文档和标准将属性称为成员。
以下是有关其中一些字段的一些附加说明。
-
用户和管理员可以验证电子邮件地址值。
具有适当 Amazon Web Services 账户 权限的管理员可以更改用户的电子邮件，并将其标记为已验证。使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes Amazon Command Line Interface (Amazon CLI) 命令将电子邮件地址标记为已验证。使用此命令，管理员可以将
email_verified属性更改为true。您也可以在 Amazon Web Services Management Console 的 Users（用户）选项卡中编辑用户，以将电子邮件地址标记为已验证。 - phone
-
如果 SMS 多重验证 (MFA) 处于活动状态，用户必须提供电话号码。有关更多信息，请参阅向用户池添加 MFA。
用户和管理员可以验证电话号码值。
具有适当 Amazon Web Services 账户 权限的管理员可以更改用户的电话号码，并将其标记为已验证。使用 AdminUpdateUserAttributes API 或 admin-update-user-attributes (Amazon CLI) 命令将电话号码标记为已验证。使用此命令，管理员可以将
phone_number_verified属性更改为true。您也可以在 Amazon Web Services Management Console的 Users（用户）选项卡中编辑用户，以将电话号码标记为已验证。重要
电话号码必须遵循以下格式规则：电话号码必须以加号 (
+) 开头，后面紧跟国家/地区代码。电话号码只能包含+号和数字。先删除电话号码中的任何其他字符，如圆括号、空格或短划线 (-)，然后再将该值提交给服务。例如，美国境内的电话号码必须遵循以下格式：+14325551212。 - preferred_username
-
您可以将
preferred_username选择为必需或别名，但不能同时选择这两者。如果preferred_username是一个别名，您可以使用 UpdateUserAttributes API 在确认用户后添加属性值。
查看必需属性
通过以下过程可查看给定用户池的必需属性。
注意
在创建用户池后，您无法更改必需属性。
username 值是一个单独的属性，与 name 属性不同。每个用户都有 username 属性。Amazon Cognito 会自动为联合身份用户生成用户名。您必须提供 username 属性以在 Amazon Cognito 目录中创建本机用户。创建用户后，您将无法更改 username 属性的值。
开发人员可以使用 preferred_username 属性为用户提供一个可以更改的用户名。有关更多信息，请参阅自定义登录属性。
如果您的应用程序不需要用户名，就不必要求用户提供用户名。您的应用程序可以在后台为用户创建唯一的用户名。如果您希望用户使用电子邮件地址和密码注册和登录，这非常有用。有关更多信息，请参阅自定义登录属性。
在用户池中，username 必须是唯一的。username 可重复使用，但只能是在您已将其删除且不再使用它的情况下。
创建用户群体时，如果您希望用户能够使用电子邮件地址或电话号码作为其用户名进行注册和登录，则可以设置用户名属性。或者，您可以设置别名属性为用户提供选项：用户可以在注册时包含多个属性，然后使用用户名、首选用户名、电子邮件地址或电话号码登录。
重要
创建用户池后，您无法更改此设置。
如何在别名属性和用户名属性之间进行选择
| 您的要求 | 别名属性 | 用户名属性 |
|---|---|---|
| Users have multiple sign-in attributes | Yes¹ | No² |
| Users must verify email address or phone number before they can sign in with it | Yes | No |
Prevent UsernameExistsException when user signs up |
Yes | No |
| Can assign the same sign-in attribute to more than one user | Yes³ | No |
¹ 可用的登录属性包括用户名、电子邮件地址、电话号码和首选用户名。
² 可以使用电子邮件地址或电话号码进行登录。
³ 只有最后验证了该属性的用户才能使用该属性登录。
如果您需要，您的用户可以在登录时使用别名输入其他属性。默认情况下，用户使用他们的用户名和密码登录。用户名是一个固定值，用户无法更改。如果您将某个属性标记为别名，用户就可以使用该属性代替用户名来登录。您可以将电子邮件地址、电话号码和首选用户名属性标记为别名。例如，如果您选择电子邮件和电话作为用户池的别名，该用户池中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。
要选择别名属性，请在创建用户群体时选择 User Name（用户名）和至少一个其他登录选项。
注意
将用户池配置为不区分大小写时，用户可以使用小写或大写字母进行注册或使用别名登录。有关更多信息，请参阅《Amazon Cognito 用户池 API 参考》中的 CreateUserPool。
如果您选择电子邮件地址作为别名，Amazon Cognito 不接受与有效电子邮件地址格式匹配的用户名。同样，如果您选择电话号码作为别名，Amazon Cognito 将不接受与有效的电话号码格式相匹配的用户池的用户名。
注意
在用户池中，别名值必须是唯一的。如果您为电子邮件地址或电话号码配置别名，那么提供的值只能在一个账户中处于已验证状态。在注册期间，如果您的用户提供电子邮件地址或电话号码作为别名值，而另一用户已使用该别名值，注册将成功。然而，当用户尝试使用此电子邮件（或电话号码）确认账户并输入有效的代码时，Amazon Cognito 会返回 AliasExistsException 错误。该错误向用户指出，已存在使用此电子邮件地址（或电话号码）的账户。此时，用户可以放弃新账户的创建，并尝试重置旧账户的密码。如果用户继续创建新账户，您的应用程序必须使用 forceAliasCreation 选项调用 ConfirmSignUp API。ConfirmSignUp 和 forceAliasCreation 结合会将别名从以前的账户移至新创建的账户，并在以前的账户中将此属性标记为未经验证。
只有在您的用户验证电话号码和电子邮件地址后，电话号码和电子邮件地址才会成为用户的活动别名。如果您将电子邮件地址和电话号码用作别名，我们建议您选择对其进行自动验证。
选择别名属性以防止用户注册时出现电子邮件地址和电话号码属性的 UsernameExistsException 错误。
激活 preferred_username 属性，以便您的用户可以更改他们用来登录的用户名，而他们的 username 属性值不会更改。如果您想设置这种用户体验，请提交新的 username 值作为 preferred_username，并选择 preferred_username 作为别名。这样，用户就可以使用输入的新值登录。如果选择 preferred_username 作为别名，您的用户只有在确认账户时才能提供该值。他们在注册期间无法提供该值。
当用户使用用户名注册时，您可以选择他们是否可以使用以下一个或多个别名登录。
-
经过验证的电子邮件地址
-
经过验证的电话号码
-
首选用户名
用户注册后可以更改这些别名。
在创建用户池时包括以下步骤，以便用户可以使用别名登录。
当用户使用电子邮件地址或电话号码作为其用户名进行注册时，您可以选择他们是否可以仅使用电子邮件地址、仅使用电话号码或其中之一进行注册。
要选择用户名属性，请在创建用户群体时不要选择 User name（用户名）作为登录选项。
电子邮件地址或电话号码必须是唯一的，并且不能已被其他用户使用。它不必经过验证。用户使用电子邮件地址或电话号码注册之后，将无法使用相同的电子邮件地址或电话号码创建新账户。如果需要，用户只能重复使用现有账户并重置账户的密码。但是，用户可以将电子邮件地址或电话号码更改为新的电子邮件地址或电话号码。如果电子邮件地址或电话号码未被使用，它将成为新的用户名。
注意
如果用户使用电子邮件地址作为用户名注册，则可以将用户名更改为另一个电子邮件地址，但他们无法将用户名更改为电话号码。如果用户使用电话号码注册，他们可以将用户名更改为另一个电话号码，但他们无法将用户名更改为电子邮件地址。
在用户池创建过程中使用以下步骤设置使用电子邮件地址或电话号码注册和登录。
注意
您不需要将电子邮件地址或电话号码标记为用户池的必需属性。
在应用程序中实施选项 2
-
调用
CreateUserPoolAPI，以创建用户池。将UserNameAttributes参数设置为phone_number、email或phone_number | email。 -
调用
SignUpAPI 并在 API 的username参数中传递电子邮件地址或电话号码。此 API 可执行以下操作：-
如果
username字符串采用有效的电子邮件格式，用户池将使用username值自动填充用户的email属性。 -
如果
username字符串采用有效的电话号码格式，用户池将使用phone_number值自动填充用户的username属性。 -
如果
username字符串格式不是电子邮件或电话号码格式，SignUpAPI 将返回异常。 -
SignUpAPI 为用户生成一个持久性 UUID，并在内部将其作为不可变的用户名属性。此 UUID 与用户身份令牌中的sub声明具有相同的值。 -
如果
username字符串包含已被使用的电子邮件地址或电话号码，SignUpAPI 将返回异常。
-
您可以使用电子邮件地址或电话号码作为别名，在除 ListUsers API 之外的所有 API 中代替用户名。调用 ListUsers 时，可以通过 email 或 phone_number 属性搜索。如果通过 username 搜索，您必须提供实际的用户名，而不是别名。
您可以将最多 50 个自定义属性添加到您的用户池。您可以为自定义属性指定一个最小和/或最大长度。但是，任何自定义属性的最大长度不能超过 2048 个字符。
每个自定义属性都具有以下特性：
-
可以将其定义为一个字符串或数字。Amazon Cognito 仅将自定义属性值作为字符串写入 ID 令牌。
-
您不能要求用户为属性提供值。
-
将其添加到用户池后，您将无法删除或更改它。
-
属性名称的字符长度在 Amazon Cognito 接受的限制范围内。有关更多信息，请参阅Amazon Cognito 中的限额。
-
它可能是可以改变的，也可能是不可改变的。在创建用户时，您只能将值写入不可改变属性。如果您的应用程序客户端具有该属性的写入权限，您可以更改可变属性的值。参阅 属性权限和范围 了解更多信息。
注意
在您的代码和 基于角色的访问控制 的规则设置中，自定义属性需要使用 custom: 前缀，以便将它们与标准属性区分开来。
通过以下过程创建新的自定义属性。
对于每个应用程序客户端，您可以为每个用户属性设置读取和写入权限。这样，您可以控制为了读取和修改您为用户存储的每个属性，任何应用程序所具有的访问权限。例如，您可以设置一个自定义属性，用于指明用户是否为付费客户。您的应用程序可能能够看到此属性，但无法直接更改它。相反，您可以使用管理工具或后台进程更新此属性。您可以通过 Amazon Cognito 控制台、Amazon Cognito API 或 Amazon CLI 设置用户属性的权限。默认情况下，任何新的自定义属性都不可用，直到您为其设置读取和写入权限。在 Amazon Cognito 控制台中创建新的应用程序客户端时，默认情况下，您将授予应用程序对所有标准和自定义属性的读写权限。要限制您的应用程序，只允许其访问其所需信息量，请选择应用程序需要的范围子集。
使用自定义属性对每个应用程序客户端重复这些步骤。
可以针对每个应用程序将属性标记为可读或可写。这对于标准属性和自定义属性均适用。应用程序可以读取您标记为可读的属性，也可以写入您标记为可写的属性。如果应用程序尝试更新不可写的属性，就会收到 NotAuthorizedException 异常。当应用程序调用 GetUser 时，只能收到该应用程序可读的属性。来自应用程序的用户 ID 令牌仅包含与可读属性相对应的声明。用户池中的必需属性始终为可写属性。如果您使用 Amazon CLI 或管理 API 来设置可写属性但不提供必需属性，就会收到 InvalidParameterException 异常。
您可以在创建用户池后更改属性权限和范围。