使用用户属性 - Amazon Cognito
标准属性用户名和首选用户名自定义登录属性自定义属性属性权限和范围
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用用户属性

属性是各种条目的信息，用于帮助您标识单个用户，如名称、电子邮件和电话号码。新的用户池有一组默认标准属性。您也可以在中的用户池定义中添加自定义属性 Amazon Web Services Management Console。本主题将详细介绍这些属性，并为您提供有关如何设置用户池的提示。

请勿将所有与用户相关的信息都应存储在属性中。例如，将频繁变化的用户数据（如使用情况统计数据或游戏分数）保存在单独的数据存储（如 Amazon Cognito Sync 或 Amazon DynamoDB）中。

在将输入的用户属性字符串值提交到用户池之前，请对其进行清理。分析建议的用户属性值的一种方法是使用 Lambda 触发器，例如注册前。

注意

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

标准属性

Amazon Cognito 根据 OpenID Connect 规范为所有用户分配一组标准属性。默认情况下，标准和自定义属性值可以是长度不超过 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_number 属性。

标准属性具有预定义的属性，您可以在 DescribeUserPool API 响应的SchemaAttributes参数中查看这些属性。您可以为这些属性设置自定义值，例如数据类型、可变性和长度限制。要修改标准属性属性，请在CreateUserPool 架构参数中设置其自定义值。您还可以在架构中设置必需的属性。在 Amazon Cognito 控制台中创建用户池时，您无法修改标准属性的属性。

注意

如果您将某个标准属性标记为 Required（必需），则用户必须为该属性提供一个值才能注册。要创建用户而不给出必填属性的值，管理员可以使用 AdminCreateUserAPI。创建用户池后，您无法在必需属性和非必需属性之间切换属性。

标准属性详细信息和格式限制
birthdate

值必须是格式中有效的 10 个字符的日期 YYYY-MM-DD。

电子邮件

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

具有适当 Amazon Web Services 账户 权限的管理员可以更改用户的电子邮件地址，也可以将其标记为已验证。使用 AdminUpdateUserAttributesAPI 或 admin-update-user-attributes Amazon Command Line Interface (Amazon CLI) 命令将电子邮件地址标记为已验证。使用此命令，管理员可以将 email_verified 属性更改为 true。您也可以在 Amazon Cognito 控制台的用户菜单中编辑用户，将电子邮件地址标记为已验证。

值必须是有效的电子邮件地址字符串，遵循标准电子邮件格式，带有 @ 符号和域名，长度不超过 2048 个字符。

phone_number

如果 SMS 多重验证 (MFA) 处于活动状态，用户必须提供电话号码。有关更多信息，请参阅 向用户池添加 MFA。

用户和管理员可以验证电话号码值。

具有适当 Amazon Web Services 账户 权限的管理员可以更改用户的电话号码，也可以将其标记为已验证。使用 AdminUpdateUserAttributesAPI 或admin-update-user-attributes Amazon CLI 命令将电话号码标记为已验证。使用此命令，管理员可以将 phone_number_verified 属性更改为 true。您也可以在 Amazon Cognito 控制台的 “用户” 菜单中编辑用户，将电话号码标记为已验证。

重要

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

preferred_username

您可以将 preferred_username 选择为必需或别名，但不能同时选择这两者。如果preferred_username是别名，则可以向 UpdateUserAttributesAPI 操作发出请求，并在确认用户后添加属性值。

sub

根据 sub 属性对用户编制索引和进行搜索。sub 属性是每个用户群体中的唯一用户标识符。用户可以更改如 phone_number 和 email 等属性。sub 属性具有固定的值。有关查找用户的更多信息，请参阅管理和搜索用户账户。

查看必需属性

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

注意

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

查看必需属性

  1. 前往 Amazon Cognito Amazon Web Services Management Console如果控制台提示您，请输入您的 Amazon 凭据。

  2. 选择 User Pools（用户池）。

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

  4. 选择 “注册” 菜单。

  5. 在 Required attributes（必需属性）部分中，查看用户池的必需属性。

用户名和首选用户名

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

开发人员可以使用 preferred_username 属性为用户提供一个他们可以更改的用户名。有关更多信息，请参阅 自定义登录属性。

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

在用户池中，username 必须是唯一的。username 可重复使用，但只能是在您已将其删除且不再使用它的情况下。有关属性的字符串限制的信息，请参阅 SignUpAPI 请求的用户名username属性。

自定义登录属性

创建用户群体时，如果您希望用户能够使用电子邮件地址或电话号码作为其用户名进行注册和登录，则可以设置用户名属性。或者，您可以设置别名属性为用户提供选项：用户可以在注册时包含多个属性，然后使用用户名、首选用户名、电子邮件地址或电话号码登录。

重要

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

如何在别名属性和用户名属性之间进行选择

您的要求 别名属性 用户名属性
用户有多个登录属性 是¹ No²
用户必须先验证电子邮件地址或电话号码，然后才能使用该地址或电话号码登录 是 否
使用重复的电子邮件地址或电话号码注册用户并防止出现UsernameExistsException错误³ 是 否
可以将相同的电子邮件地址或电话号码属性值分配给多个用户 是⁴ 否

¹ 可用的登录属性包括用户名、电子邮件地址、电话号码和首选用户名。

² 可以使用电子邮件地址或电话号码进行登录。

³ 当用户使用可能重复的电子邮件地址或电话号码注册但没有用户名时，您的用户群体不会生成 UsernameExistsException 错误。此行为独立于防止用户名存在错误，此错误适用于登录操作，但不适用于注册操作。

⁴ 只有最后验证了该属性的用户才能使用该属性登录。

当用户有用户名但也可以使用该属性登录时，属性就是别名。如果要允许用户在登录表单的用户名字段中选择用户名和其他属性值，请设置别名。该username属性是用户无法更改的固定值。如果您将某个属性标记为别名，用户就可以使用该属性代替用户名来登录。您可以将电子邮件地址、电话号码和首选用户名属性标记为别名。例如，如果您选择电子邮件地址和电话号码作为用户群体的别名，该用户群体中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。

要选择别名属性，请在创建用户群体时选择 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 作为别名，您的用户只有在确认账户时才能提供该值。他们在注册期间无法提供该值。

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

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

  • 经过验证的电话号码

  • 首选用户名

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

重要

当您的用户群体支持使用别名登录，并且您想要向用户授权或查找用户时，请不要通过用户的任何登录属性来识别您的用户。固定值的用户标识符 sub 是用户身份的唯一一致指标。

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

Phone number or email address (console)

创建用户池时，必须将电子邮件地址和电话号码设置为别名属性。

在 Amazon Cognito 控制台中创建带有用户名别名的用户池

  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您，请输入您的 Amazon 凭据。

  2. 使用 “开始使用” 或 “创建用户池” 按钮创建新的用户池。

  3. 在 “定义您的应用程序” 中选择应用程序设置。

  4. 在 “登录标识符选项” 下的 “配置选项” 中，选中 “用户名” 旁边的复选框以及至少一个其他选项，即电子邮件和电话号码。

  5. 选择您的别名属性作为注册的必填属性。在托管登录注册表单中，Amazon Cognito 会提示新用户为必填属性提供值。

  6. 在 “添加返回 URL” 下，为托管登录登录后的重定向设置应用程序回调 URL。

  7. 选择创建。

Phone number or email address (API/SDK)

使用 CreateUserPoolAPI 操作创建新的用户池。如图所示配置AliasAttributes参数。如果您只需要电话号码别名，则可以删除该email条目；如果您只需要电子邮件地址别名，则可以删除该phone_number条目。

"AliasAttributes": [
   "email",
   "phone_number"
],
Preferred username (API/SDK)

Amazon Cognito 控制台创建不preferred_username使用别名的用户池。要使用preferred_username别名创建用户池，请在 Amazon SDK 中设置包含 CreateUserPoolAPI 请求的用户池。要支持在注册时创建首选用户名属性，请preferred_username将其设置为必填属性。在托管登录注册表单中，Amazon Cognito 会提示新用户为必填属性提供值。您可以在 Amazon Cognito 控制台中将其设置preferred_username为必填属性，但这并不能将其作为别名使用。

配置为别名

preferred_username如图所示，在CreateUserPool请求的AliasAttributes参数中配置为别名。从列表中移除任何你不想作为别名属性的值。

"AliasAttributes": [
   "email",
   "phone_number",
   "preferred_username"
],
根据需要进行配置

在托管登录注册表单中，Amazon Cognito 会提示新用户为必填属性提供值。preferred_username根据需要在CreateUserPool请求的SchemaAttributes参数中进行配置。

要将首选用户名设置为必填属性，请按如下所示进行配置。以下示例修改了的默认架构preferred_username，使其根据需要进行设置。其他架构参数AttributeDataType（默认为string）和StringAttributeConstraints（长度默认为 1-99 个字符）采用默认值。

"Schema": [
   {
      "Name": "preferred_username",
      "Required": true
   }
]

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

要选择用户名属性，请在创建用户池时不要选择 “用户名” 作为登录选项。

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

当您同时选择电子邮件地址和电话号码作为用户名属性时，用户可以使用其中一个属性登录，即使他们为这两个属性都提供了值。登录用户名基于您在Username参数中传递的SignUp值。

注意

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

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

Username attributes (console)

以下过程使用电子邮件地址或电话号码用户名属性创建用户池。在 Amazon Cognito 控制台中设置用户名属性的过程的不同之处在于，您不必同时将用户名设置为登录属性。

在 Amazon Cognito 控制台中创建具有用户名属性的用户池

  1. 转到 Amazon Web Services Management Console中的 Amazon Cognito。如果控制台提示您，请输入您的 Amazon 凭据。

  2. 使用 “开始使用” 或 “创建用户池” 按钮创建新的用户池。

  3. 在 “定义您的应用程序” 中选择应用程序设置。

  4. 在登录标识符选项下的配置选项中，选择您的用户名属性：电子邮件、电话号码或两者。取消选中用户名。

  5. 作为最佳实践，请选择您的用户名属性作为注册的必填属性。在托管登录注册表单中，Amazon Cognito 会提示新用户为必填属性提供值。如果您未按要求设置用户名属性，Amazon Cognito 不会提示新用户为其提供值。在这种情况下，您必须将应用程序配置为收集和提交每个用户的电子邮件地址或电话号码，然后他们才能登录。

  6. 在 “添加返回 URL” 下，为托管登录登录后的重定向设置应用程序回调 URL。

  7. 选择创建。

Username attributes (API/SDK)

在CreateUserPool请求中，如图所示配置UsernameAttributes参数。要仅允许使用电子邮件地址用户名登录，请在此列表中email单独指定。要仅允许使用电话号码用户名登录，请单独指定。phone_number此参数取代用户名作为登录选项。

"UsernameAttributes": [ 
   "email",
   "phone_number"
],

配置用户名属性时，可以发出 SignUpAPI 请求，在username参数中传递电子邮件地址或电话号码。以下是带有用户名属性的代码 SignUp API 操作的行为。

  • 例如，如果username字符串采用有效的电子邮件地址格式user@example.com，则用户池会自动使用该username值填充用户的email属性。

  • 例如，如果username字符串采用有效的电话号码格式+12065551212，则用户池会自动使用该username值填充用户的phone_number属性。

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

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

  • SignUpAPI 会使用您的用户的 UUID 填充该username属性。此 UUID 与用户身份令牌中的 sub 声明具有相同的值。

APIs除了操作之外，您还可以在所有ListUsers操作中使用电子邮件地址或电话号码代替用户名。在 ListUsers API 请求中，您可以指定Filteremail或phone_number。如果筛选依据username，则必须提供 UUID 用户名，而不是电子邮件地址或电话号码。

自定义属性

您可以将最多 50 个自定义属性添加到您的用户池。您可以为自定义属性指定一个最小和/或最大长度。但是，任何自定义属性的最大长度不能超过 2048 个字符。自定义属性的名称必须与Name参数中描述的正则表达式模式相匹配SchemaAttributeType。

每个自定义属性都具有以下特性：

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

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

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

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

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

注意

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

在创建用户池时，您还可以在的属性中添加开发者属性CreateUserPool。SchemaAttributes开发人员属性具有 dev: 前缀。您只能使用 Amazon 凭证修改用户的开发者属性。开发人员属性是一项旧版特征，Amazon Cognito 已将其替换为应用程序客户端读写权限。

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

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

  1. 前往 Amazon Cognito Amazon Web Services Management Console如果控制台提示您，请输入您的 Amazon 凭据。

  2. 选择 User Pools（用户池）。

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

  4. 选择 “注册” 菜单，然后在 “自定义属性” 部分中，选择 “添加自定义属性”。

  5. 在存储库的 Add custom attributes（添加自定义属性）页面上，提供有关新属性的以下详细信息：

    • 输入 Name（名称）。

    • 选择 Type（类型）（字符串或数字）。

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

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

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

  6. 选择 Save changes（保存更改）。

属性权限和范围

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

妥善做法是在创建应用程序客户端时指定属性的读取和写入权限。向您的应用程序客户端授予应用程序运行所需的最小用户属性集的访问权限。

注意

DescribeUserPoolClient只有在配置默认权限之外的应用程序客户端权限WriteAttributes时，才会返回ReadAttributes和的值。

更新属性权限（Amazon Web Services Management Console）

  1. 前往 Amazon Cognito Amazon Web Services Management Console如果控制台提示您，请输入您的 Amazon 凭据。

  2. 选择 User Pools（用户池）。

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

  4. 选择 “应用程序客户端” 菜单，然后从列表中选择一个应用程序客户端。

  5. 在 “属性权限” 选项卡中，选择 “编辑”。

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

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

对于每个应用程序客户端，您可以将属性标记为可读或可写。这对于标准属性和自定义属性均适用。您的应用程序可以检索您标记为可读的属性的值，也可以设置或修改您标记为可写的属性的值。如果您的应用程序尝试为其无权写入的属性设置值，Amazon Cognito 会返回。NotAuthorizedException GetUser请求包括带有应用程序客户端声明的访问令牌；Amazon Cognito 仅返回应用程序客户端可以读取的属性的值。来自应用程序的用户 ID 令牌仅包含与可读属性相对应的声明。所有应用程序客户端都可以写入用户群体所需的属性。仅当您还为尚未具有值的必需属性提供值时，才能在 Amazon Cognito 用户群体 API 请求中设置相应属性的值。

自定义属性具有不同的读写权限特征。您可以将它们创建为用户群体的可变或不可变属性，并可以将它们设置为任何应用程序客户端的读或写属性。

在创建用户期间，不可变的自定义属性可以更新一次。您可以使用以下方法填充不可变的属性。

  • SignUp：用户注册了一个应用程序客户端，该客户端具有对不可变自定义属性的写访问权限。它们为该属性提供了一个值。

  • 使用第三方 IdP 登录：用户登录到一个应用程序客户端，该客户端具有对不可变自定义属性的写访问权限。IdP 的用户群体配置有一条规则，可以将提供的声明映射到不可变的属性。这可以实现，但不太实际，因为用户只能登录一次。在首次登录后，如果用户尝试再次登录，Amazon Cognito 会因为映射规则指向一个现在不可写的属性而拒绝登录尝试。

  • AdminCreateUser：您为不可变属性提供一个值。

使用范围的属性权限

在使用 Amazon SDK 或 CDK、REST API 或配置的用户池中 Amazon CLI，您可以使用 OIDC 范围配置应用程序客户端的读取或写入权限。oidc:profileoidc: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 节中所定义。有关您可以分配给应用程序客户端的范围的信息，请参阅作用域、M2M 以及 APIs 带资源服务器的场景。

要将您的应用程序客户端配置为写入oidc:profile作用域下的属性，请在CreateUserPoolClient或 UpdateUserPoolClientAPI 请求中WriteAttributes将oidc:profile的值设置为，以及您希望允许应用程序修改的任何其他属性。同样，要授予对这些属性的读取权限，oidc:profile请添加的值ReadAttributes。

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