用户池属性 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

用户池属性

属性是各种条目的信息,用于帮助您标识单个用户,如名称、电子邮件和电话号码。新的用户池有一组默认标准属性。您也可以在 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(电话)。

注意

一些文档和标准将属性称为成员

以下是有关其中一些字段的一些附加说明。

email

用户和管理员可以验证电子邮件地址值。

具有适当 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 在确认用户后添加属性值。

查看必需属性

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

注意

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

Original console
查看必需属性
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 Manage User Pools(管理用户池)。

  3. Your User Pools(您的用户池)页面上,选择一个用户池。

  4. 在左侧的导航菜单中,选择 Attributes(属性)。

  5. Which standard attributes are required?(哪些标准属性为必需属性?)下,查看用户池的必需属性。

New console
查看必需属性
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 User Pools(用户池)。

  3. 从列表中选择现有用户池。

  4. 选择 Sign-up experience(注册体验)选项卡。

  5. Required attributes(必需属性)部分中,查看用户池的必需属性。

username 值是一个单独的属性,与 name 属性不同。每个用户都有 username 属性。Amazon Cognito 会自动为联合身份用户生成用户名。您必须提供 username 属性以在 Amazon Cognito 目录中创建本机用户。创建用户后,您将无法更改 username 属性的值。

开发人员可以使用 preferred_username 属性为用户提供一个可以更改的用户名。有关更多信息,请参阅Aliases

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

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

如果您需要,您的用户可以在登录时使用别名输入其他属性。默认情况下,用户使用他们的用户名和密码登录。用户名是一个固定值,用户无法更改。如果您将某个属性标记为别名,用户就可以使用该属性代替用户名来登录。您可以将电子邮件地址、电话号码和首选用户名属性标记为别名。例如,如果您选择电子邮件和电话作为用户池的别名,该用户池中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。

注意

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

如果您选择电子邮件地址作为别名,Amazon Cognito 不接受与有效电子邮件地址格式匹配的用户名。同样,如果您选择电话号码作为别名,Amazon Cognito 将不接受与有效的电话号码格式相匹配的用户池的用户名。

注意

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

只有在您的用户验证电话号码和电子邮件地址后,电话号码和电子邮件地址才会成为用户的活动别名。因此,如果您将电子邮件地址和电话号码用作别名,我们建议您选择对其进行自动验证。

激活 preferred_username 属性,以便您的用户可以更改他们用来登录的用户名,而他们的 username 属性值不会更改。如果您想设置这种用户体验,请提交新的 username 值作为 preferred_username,并选择 preferred_username 作为别名。这样,用户就可以使用输入的新值登录。如果选择 preferred_username 作为别名,您的用户只有在确认账户时才能提供该值。他们在注册期间无法提供该值。

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

创建用户池时,您可以选择是否希望用户使用电子邮件地址或电话号码作为用户名进行注册。

注意

创建用户池后,您无法更改此设置。

当用户使用用户名注册时,您可以选择他们是否可以使用以下一个或多个别名登录:

  • 经过验证的电子邮件地址

  • 经过验证的电话号码

  • 首选用户名

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

在创建用户池时包括以下步骤,以便用户可以使用别名登录。

Original console
配置用户池使用别名登录
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 Manage User Pools(管理用户池)。

  3. 在页面右上角,选择 Create a user pool(创建用户池)。

  4. 在页面左上角,选择 Review(查看)。

  5. Attributes(属性)选项卡中,在 How do you want your end users to sign-in?(您希望您的最终用户如何注册和登录?)中选择 Username(用户名)。然后选择以下任一选项:

    • Also allow sign in with verified email address(还允许使用经验证的电子邮件地址登录):此选项允许用户使用其电子邮件地址登录。

    • Also allow sign in with verified phone number(还允许使用经验证的电话号码登录):此选项允许用户使用其电话号码登录。

    • Also allow sign in with preferred username(还允许使用首选用户名登录):此选项允许用户使用首选的用户名登录。用户可以更改此用户名。

  6. 选择 Next step(下一步)保存,然后完成向导中的所有步骤。

New console
配置用户池以便用户可以使用首选用户名登录
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 User Pools(用户池)。

  3. 在页面右上角,选择 Create a user pool(创建用户池)以开启用户池创建向导。

  4. Configure sign-in experience(配置登录体验)中,选择您想将其与用户池关联的身份 Provider types(提供商类型)。

  5. Cognito user pool sign-in options(Cognito 用户池登录选项)下,选择 User name(用户名)、Email(电子邮件)和 Phone number(电话号码)的任意组合。

  6. User name requirements(用户名要求)下,选择 Allow users to sign in with a preferred user name(允许用户使用首选用户名登录),以便用户可以设置登录时要使用的备用用户名。

  7. 选择 Next(下一步),然后完成向导中的所有步骤。

当用户使用电子邮件地址或电话号码作为其用户名进行注册时,您可以选择他们是否可以仅使用电子邮件地址、仅使用电话号码或其中之一进行注册。

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

注意

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

在用户池创建过程中使用以下步骤设置使用电子邮件地址或电话号码注册和登录。

Original console
配置用户池使用电子邮件地址或电话号码注册和登录
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 Manage User Pools(管理用户池)。

  3. 在页面右上角,选择 Create a user pool(创建用户池)。

  4. 在页面左上角,选择 Review(查看)。

  5. Attributes(属性)选项卡中的 How do you want your end users to sign-in?(您希望您的最终用户如何登录?)下,选择 Email address or phone number(电子邮件地址或电话号码)。然后选择以下任一选项:

    • Allow email addresses(允许使用电子邮件地址):允许用户使用电子邮件作为用户名注册。

    • Allow phone numbers(允许使用电话号码):允许用户使用电话号码作为用户名注册。

    • Allow both email addresses and phone number (users can choose one)(允许同时使用电子邮件地址和电话号码(用户可选择其中一个)):允许用户在注册过程中使用电子邮件地址或电话号码作为用户名。

  6. 选择 Next step(下一步)保存,然后完成向导中的所有步骤。

New console
配置用户池使用电子邮件地址或电话号码注册和登录
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 User Pools(用户池)。

  3. 在页面右上角,选择 Create a user pool(创建用户池)以开启用户池创建向导。

  4. Cognito user pool sign-in options(Cognito 用户池登录选项)下,选择 User name(用户名)、Email(电子邮件)和 Phone number(电话号码)的任意组合,表示用户可用于登录的别名属性。

  5. User name requirements(用户名要求)下,选择下列一个或两个选项:

    Allow users to sign in with a preferred user name(允许用户使用首选用户名登录)

    允许用户使用首选用户名登录。用户可以更改此用户名。

    Make user name case sensitive(使用户名区分大小写)

    将用户名设置为区分大小写,其中 ExampleUserexampleuser 是唯一的用户名。

  6. 选择 Next(下一步),然后完成向导中的所有步骤。

注意

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

在应用程序中实施选项 2
  1. 调用 CreateUserPool API,以创建用户池。将 UserNameAttributes 参数设置为 phone_numberemailphone_number | email

  2. 调用 SignUp API 并在 API 的 username 参数中传递电子邮件地址或电话号码。此 API 可执行以下操作:

    • 如果 username 字符串采用有效的电子邮件格式,用户池将使用 username 值自动填充用户的 email 属性。

    • 如果 username 字符串采用有效的电话号码格式,用户池将使用 phone_number 值自动填充用户的 username 属性。

    • 如果 username 字符串格式不是电子邮件或电话号码格式,SignUp API 将返回异常。

    • SignUp API 为用户生成一个持久性 UUID,并在内部将其作为不可变的用户名属性。此 UUID 与用户身份令牌中的 sub 声明具有相同的值。

    • 如果 username 字符串包含已被使用的电子邮件地址或电话号码,SignUp API 将返回异常。

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

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

每个自定义属性都具有以下特性:
  • 可以将其定义为一个字符串或数字。Amazon Cognito 仅将自定义属性值作为字符串写入 ID 令牌。

  • 您不能要求用户为属性提供值。

  • 将其添加到用户池后,您将无法删除或更改它。

  • 属性名称的字符长度在 Amazon Cognito 接受的限制范围内。有关更多信息,请参阅Amazon Cognito 中的限额

  • 它可能是可以改变的,也可能是不可改变的。在创建用户时,您只能将值写入不可改变属性。如果您的应用程序客户端具有该属性的写入权限,您可以更改可变属性的值。参阅 属性权限和范围 了解更多信息。

注意

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

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

Original console
通过控制台添加自定义属性
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 Manage User Pools(管理用户池)。

  3. Your User Pools(您的用户池)页面上,选择要配置的用户池。

  4. 在左侧的导航栏中,选择 Attributes(属性)。

  5. Do you want to add custom attributes?(是否要添加自定义属性?)下,选择 Add custom attribute(添加自定义属性)。

  6. 提供有关新属性的以下详细信息:

    • 输入 Name(名称)。

    • 选择 Type(类型)(字符串数字)。

    • 输入最小字符串长度或数字值。

    • 输入最大字符串长度或数字值。

    • 如果您想授予用户在设置初始值后更改自定义属性值的权限,请选择 Mutable(可变)。

  7. 选择保存更改

New console
使用控制台添加自定义属性
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 User Pools(用户池)。

  3. 从列表中选择现有用户池。

  4. 选择 Sign-up experience(注册体验)选项卡,然后在 Custom attributes(自定义属性)部分,选择 Add custom attributes(添加自定义属性)。

  5. 在存储库的 Add custom attributes(添加自定义属性)页面上,提供有关新属性的以下详细信息:

    • 输入 Name(名称)。

    • 选择 Type(类型)(字符串数字)。

    • 输入最小字符串长度或数字值。

    • 输入最大字符串长度或数字值。

    • 如果您想授予用户在设置初始值后更改自定义属性值的权限,请选择 Mutable(可变)。

  6. 选择保存更改

对于每个应用程序客户端,您可以为每个用户属性设置读取和写入权限。这样,您可以控制为了读取和修改您为用户存储的每个属性,任何应用程序所具有的访问权限。例如,您可以设置一个自定义属性,用于指明用户是否为付费客户。您的应用程序可能能够看到此属性,但无法直接更改它。相反,您可以使用管理工具或后台进程更新此属性。您可以通过 Amazon Cognito 控制台、Amazon Cognito API 或 Amazon CLI 设置用户属性的权限。默认情况下,任何新的自定义属性都不可用,直到您为其设置读取和写入权限。在 Amazon Cognito 控制台中创建新的应用程序客户端时,默认情况下,您将授予应用程序对所有标准和自定义属性的读写权限。要限制您的应用程序,只允许其访问其所需信息量,请选择应用程序需要的范围子集。

Original console
通过控制台更新属性权限
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 Manage User Pools(管理用户池)。

  3. Your User Pools(您的用户池)页面上,选择要配置的用户池。

  4. 在左侧导航栏中,选择 App clients(应用程序客户端)。

  5. 为要更新的应用程序客户端选择 Show Details(显示详细信息)。

  6. 在页面底部,选择 Set attribute read and write permissions(设置属性读取和写入权限),然后配置读取和写入权限。

  7. 选择 Save app client changes(保存应用程序客户端更改)。

New console
通过控制台更新属性权限
  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您,请输入 Amazon 凭证。

  2. 选择 User Pools(用户池)。

  3. 从列表中选择现有用户池。

  4. 选择 App integration(应用程序集成)选项卡,然后在 App clients(应用程序客户端)部分,从列表中选择应用程序客户端。

  5. Attribute read and write permissions(属性读取和写入权限)部分,选择 Edit(编辑)。

  6. Edit attribute read and write permissions(编辑设置属性读取和写入权限)页面上,配置读取和写入权限,然后选择 Save changes(保存更改)。

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

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

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