用户池属性
属性是各种条目的信息,用于帮助您标识单个用户,如名称、电子邮件和电话号码。创建一个新的用户池后,您将获得一组默认属性,称为“标准属性”。您也可以在 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
)有格式限制。只能验证电子邮件和电话。
在此规范中,属性称为成员。
以下是有关上述某些字段的一些附加说明。
-
电子邮件地址值可以进行验证。
具有适当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
作为别名,只有在确认账户后才能提供该值。在注册期间无法提供该值。
使用别名简化用户注册和登录
在用户池创建过程中,您可以选择是否允许用户使用电子邮件地址或电话号码作为其用户名注册。
在用户池创建完成后,您无法更改此设置。
在这种情况下,用户使用用户名注册。此外,您可以选择性地允许用户使用以下一个或多个别名登录:
-
经过验证的电子邮件地址
-
经过验证的电话号码
-
首选的用户名
用户注册后可以更改这些别名。
在用户池创建过程中通过以下步骤,以允许使用别名登录。
在这种情况下,用户使用电子邮件地址或电话号码作为其用户名注册。您可以选择是否允许仅使用电子邮件地址、仅使用电话号码或使用任意一项进行注册。
电子邮件或电话号码必须是唯一的,并且不能已被其他用户使用。它不必经过验证。用户使用电子邮件或电话号码注册之后,将无法使用相同的电子邮件或电话号码创建新账户。如果需要,用户只能重复使用现有账户并重置账户的密码。但是,用户可以将电子邮件或电话号码更改为新的电子邮件或电话号码;如果电子邮件或电话号码未被使用,它将成为新的用户名。
如果用户使用电子邮件地址作为用户名注册,则可以将用户名更改为另一个电子邮件地址;他们无法将用户名更改为电话号码。如果用户使用电话号码注册,他们可以将用户名更改为另一个电话号码;他们无法将用户名更改为电子邮件地址。
在用户池创建过程中通过以下步骤,以允许使用电子邮件或电话号码注册和登录。
您不需要将电子邮件或电话号码标记为用户池的必需属性。
在应用程序中实施选项 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:
前缀,以便将它们与标准属性区分开来。
通过以下过程创建新的自定义属性。
您可以为每个应用程序的每个用户属性设置读取和写入权限。这使您能够控制哪些应用程序可以对存储的每个用户属性进行查看和修改。例如,您可以设置一个自定义属性,用于指明用户是否为付费客户。您的应用程序可以查看此属性,但无法直接修改。相反,您可以使用管理工具或后台进程更新此属性。可以通过 Amazon Cognito 控制台、API 或 Amazon CLI 设置用户属性的权限。默认情况下,任何新的自定义属性都不可用,直到您为其设置读取和写入权限。
使用自定义属性对每个应用程序客户端重复这些步骤。
可以针对每个应用程序将属性标记为可读或可写。这对于标准属性和自定义属性均适用。应用程序可以读取标记为可读的属性,也可以编写标记为可写的属性。如果应用程序尝试更新不可写的属性,就会收到 NotAuthorizedException
异常。当应用程序调用 GetUser 时,只能收到该应用程序可读的属性。经过身份验证后发出的 ID 令牌仅包含与可读属性相对应的声明。用户池中的必需属性始终为可写属性。如果您使用 Amazon CLI 或管理 API 来设置可写属性但不提供必需属性,就会出现 InvalidParameterException
异常。
您可以在创建用户池后更改属性权限和范围。