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

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

配置用户池属性

您将获得一组适用于所有用户池的默认属性，称为“标准属性”。您也可以在 Amazon Web Services Management Console 中为您的用户池定义添加自定义属性。本主题将详细介绍这些属性，并为您提供有关如何设置用户池的提示。

属性是各种条目的信息，用于帮助您标识单个用户，如名称、电子邮件和电话号码。

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

标准属性

以下是适用于用户池中所有用户的标准属性。这些属性是按照 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

这些属性作为所有用户的可选属性提供。要将某个属性设置为必需属性，请选中该属性旁的复选框。

注意

如果某个标准属性被标记为必需属性，则用户必须为该属性提供一个值才能注册。通过使用 AdminCreateUser API，管理员无需为必需属性提供值就可以创建用户。在用户池创建完成后，属性就不能在必需与非必需之间切换。

默认情况下，标准和自定义属性值可以是任何不超过 2048 个字符的字符串，但是某些属性值（例如 updated_at）有格式限制。只能验证电子邮件和电话。

注意

在此规范中，属性被称为成员。

以下是有关上述某些字段的一些附加说明。

email

电子邮件地址值可以进行验证。

具有适当的管理员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 进行确认后再添加属性值。

 

编辑标准属性

  1. 在属性选项卡上，选择用户注册所需的属性。如果某个属性为必需属性，则用户在未提供该必需属性的情况下，将无法注册。

    重要

    在创建用户池后，将无法更改这些要求。

  2. 要为电子邮件、电话号码、地址或首选用户名创建别名，请选择别名。有关别名的更多信息，请参阅别名概述。

  3. 继续创建 自定义属性。

 

用户名和首选用户名

username 值是一个单独的属性，与 name 属性不同。在注册用户时，username 始终为必需项，并且在用户创建后无法更改。

开发人员可以使用 preferred_username 属性让用户设置一个可以更改的用户名。有关更多信息，请参阅 别名概述。

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

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

别名概述

您可以允许最终用户通过使用别名使用多个标识符登录。

默认情况下，用户使用他们的用户名和密码登录。用户名是一个固定值，用户无法更改。如果您将某个属性标记为别名，用户就可以使用该属性代替用户名来登录。电子邮件地址、电话号码和首选用户名属性都可以标记为别名。

例如，如果电子邮件和电话被选为用户池的别名，该用户池中的用户就可以将用户名、电子邮件地址或电话号码与密码一起使用进行登录。

注意

当您将用户池配置为不区分用户名大小写时，您可以选择在别名中使用小写或大写字母登录或注册。有关更多信息，请参阅 。CreateUserPool中的Amazon Cognito 用户池 API 参考。

如果电子邮件被选为别名，用户名将无法匹配有效的电子邮件格式。同样，如果电话号码被选为别名，该用户池的服务将不接受与有效的电话号码模式相匹配的用户名。

注意

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

电话号码和电子邮件地址只有经过验证之后才能成为用户的有效别名。因此，如果您将电子邮件地址和电话号码用作别名，我们建议您选择对其进行自动验证。使用 preferred_username 属性，用户便可拥有更改用户名的体验，但实际上用户的实际用户名值不可更改。

如果您想实现这种用户体验，请提交新的 username 值作为 preferred_username，并选择 preferred_username 作为别名。这样，用户就可以使用输入的新值登录。

如果选择 preferred_username 作为别名，只有在确认账户后才能提供该值。在注册期间无法提供该值。

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

在属性控制台选项卡中，您可以选择是否允许用户使用电子邮件地址或电话号码作为其用户名登录。

注意

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

选项 1：用户使用用户名注册并使用用户名或别名登录

在这种情况下，用户使用用户名注册。此外，您可以选择性地允许用户使用以下一个或多个别名登录：

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

  • 经过验证的电话号码

  • 首选的用户名

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

使用以下步骤在控制台中配置您的用户池，以允许使用别名登录。

配置用户池使用别名登录

  1. 在属性选项卡中，在您希望您的最终用户如何注册和登录？中选择用户名。

  2. 请选择以下任一选项：

    • 还允许使用已验证的电子邮件地址登录：此选项允许用户使用其电子邮件地址进行登录。

    • 还允许使用已验证的电话号码登录：此选项允许用户使用其电话号码进行登录。

    • 还允许使用首选用户名登录：此选项允许用户使用首选的用户名进行登录。用户可以更改此用户名。

选项 2：用户使用电子邮件或电话号码注册和登录，而不是用户名

在这种情况下，用户使用电子邮件地址或电话号码作为其用户名注册。您可以选择是否允许仅使用电子邮件地址、仅使用电话号码或使用任意一项进行注册。

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

注意

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

使用以下步骤在控制台中配置您的用户池，以允许使用电子邮件或电话号码注册和登录。

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

  1. 在属性选项卡中的您希望您的最终用户如何注册和登录？下，选择电子邮件地址或电话号码。

  2. 请选择以下任一选项：

    • 允许电子邮件地址：此选项允许用户使用电子邮件作为用户名注册。

    • 允许电话号码：此选项允许用户使用电话号码作为用户名注册。

    • 同时允许电子邮件地址和电话号码（用户可以选择一个）：此选项允许用户在注册过程中使用电子邮件地址或电话号码作为用户名。

注意

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

在应用程序中实施选项 2

  1. 调用 CreateUserPool API，以创建用户池。将 UserNameAttributes 参数设置为 phone_number、email 或 phone_number | email。

  2. 调用 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 搜索，则必须提供实际的用户名，而不是别名。

自定义属性

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

每个自定义属性：

  • 可以定义为一个字符串或数字。

  • 不能是必需的。

  • 一旦添加到用户池，就不能删除或更改。

  • 可以有一个名称，此名称的字符长度符合 Amazon Cognito 接受的限制。有关更多信息，请参阅 Amazon Cognito 中的配额。

注意

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

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

  1. 在左侧的导航栏中，选择属性。

  2. 对于每个新属性：

    1. 选择是否要添加自定义属性？下的添加其他属性。

    2. 为每个自定义属性选择特性，例如数据类型（字符串或数字）、名称、最小长度和最大长度。

    3. 如果您想让用户能够在为自定义属性提供值后更改该值，请选择可变。

属性权限和范围

您可以为每个用户属性设置每个应用程序的读取和写入权限。这使您能够控制哪些应用程序可以对存储的每个用户属性进行查看和/或修改。例如，您可以设置一个自定义属性，用于指明用户是否为付费客户。您的应用程序可以查看此属性，但无法直接修改。相反，您可以使用管理工具或后台进程更新此属性。可以通过 Amazon Cognito 控制台、API 或 CLI 设置用户属性的权限。默认情况下，任何新的自定义属性都不可用，直到您为其设置读取和写入权限。

使用控制台设置或更改属性权限

  1. 在左侧的导航栏中，选择应用程序客户端。

  2. 为要更新的应用程序客户端选择显示详细信息。

  3. 选择为每个属性设置属性读取和写入权限。

  4. 选择保存应用程序客户端更改。

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

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

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