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

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

用户池属性

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

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

注意

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

标准属性

Amazon Cognito 根据 OpenID Connect 规范为所有用户分配一组标准属性。默认情况下，标准和自定义属性值可以是长度不超过 2048 个字符的任何字符串，但是某些属性值有格式限制。

标准属性是：

  • address

  • birthdate

  • email

  • family_name

  • gender

  • given_name

  • locale

  • middle_name

  • name

  • nickname

  • phone_number

  • picture

  • preferred_username

  • profile

  • sub

  • updated_at

  • website

  • zoneinfo

除 sub 外，默认情况下，对于所有用户，标准属性都是可选的。要将某个属性设置为必需属性，请在用户池创建过程中，选择属性旁边的 Required（必需）复选框。Amazon Cognito 为每个用户的 sub 属性分配一个唯一的用户标识符值。只能验证 email 和 phone_number 属性。

注意

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

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

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

email

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

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

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

phone_number

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

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

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

重要

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

preferred_username

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

sub

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

查看必需属性

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

注意

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

查看必需属性

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

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

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

  4. 选择 Sign-up experience（注册体验）选项卡。

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

用户名和首选用户名

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

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

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

在用户池中，username 必须是唯一的。username 可重复使用，但只能是在您已将其删除且不再使用它的情况下。有关属性的字符串限制的信息，请参阅 SignUpAPI 请求的用户名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
Sign up users with duplicate email addresses or phone numbers and prevent UsernameExistsException errors³ Yes No
Can assign the same email address or phone number attribute value to more than one user Yes⁴ No

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

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

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

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

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

要选择别名属性，请在创建用户群体时选择 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 是用户身份的唯一一致指标。

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

配置用户群体以便用户可以使用首选用户名登录

  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. 在用户名要求下，选择允许用户使用首选用户名登录，以便用户可以设置登录时要使用的备用用户名。

  7. 选择 Next（下一步），然后完成向导中的所有步骤。

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

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

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

注意

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

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

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

  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 用户群体登录选项）下，选择 Email（电子邮件）和 Phone number（电话号码）的任意组合，这表示用户可用于登录的属性。

  5. 选择 Next（下一步），然后完成向导中的剩余步骤。

注意

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

在应用程序中实施选项 2

  1. 调用 CreateUserPool API，以创建用户池。将 UserNameAttributes 参数设置为 phone_number、email 或 phone_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 时，可以通过 email 或 phone_number 属性搜索。如果通过 username 进行搜索，您必须提供实际的用户名，而不是别名。

自定义属性

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

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

  • 可以将其定义为一个字符串或数字。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. 选择 Sign-up experience（注册体验）选项卡，然后在 Custom attributes（自定义属性）部分，选择 Add custom attributes（添加自定义属性）。

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

    • 输入 Name（名称）。

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

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

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

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

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

属性权限和范围

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

注意

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

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

  1. 前往 Amazon Cognito Amazon Web Services Management Console如果控制台提示您，请输入您的 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（保存更改）。

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

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

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

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

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

  • 使用第三方 IdP 登录：用户登录到一个应用程序客户端，该客户端具有对不可变自定义属性的写访问权限。IdP 的用户群体配置有一条规则，可以将提供的声明映射到不可变的属性。

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

有关您可以分配给应用程序客户端的范围的信息，请参阅使用资源服务器的 OAuth 2.0 范围和 API 授权。

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