指定适用于用户池的身份提供商属性映射 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

指定适用于用户池的身份提供商属性映射

您可以使用 Amazon Web Services Management Console、Amazon CLI 或 API 来指定用户池的身份提供商 (IdP) 的属性映射。

有关映射的需知信息

在开始设置用户属性映射之前,请查看以下重要细节。

  • 当联合用户登录到您的应用程序时,您的用户群体需要的每个用户群体属性都必须存在一个映射。例如,如果您的用户群体需要 email 属性来进行注册,则将此属性映射到 IdP 中的对等属性。

  • 默认情况下,映射的电子邮件地址未经验证。您无法使用一次性代码验证映射的电子邮件地址。而是要映射 IdP 的属性来获取验证状态。例如,Google 和大多数 OIDC 提供商都包含 email_verified 属性。

  • 您可以将身份提供者(IdP)令牌映射到用户群体中的自定义属性。社交提供者提供访问令牌,而 OIDC 提供者提供访问令牌和 ID 令牌。要映射令牌,请添加一个最大长度为 2048 个字符的自定义属性,向您的应用程序客户端授予对该属性的写入权限,然后将 access_tokenid_token 从 IdP 映射到自定义属性。

  • 对于每个映射的用户群体属性,最大值长度 2048 个字符必须足够大,才能容纳 Amazon Cognito 从 IdP 处获取的值。否则,当用户登录到您的应用程序时,Amazon Cognito 会报告错误。当令牌长度超过 2048 个字符时,Amazon Cognito 不支持将 IdP 令牌映射到自定义属性。

  • Amazon Cognito 从您的联合 IdP 通过的特定声明中衍生出联合用户个人资料中的username属性,如下表所示。例如,Amazon Cognito 会在这个属性值前面加上你的 IdP 的名字。MyOIDCIdP_[sub]如果您希望您的联合用户拥有与外部用户目录中的属性完全匹配的属性,请将该属性映射到 Amazon Cognito 登录属性,例如。preferred_username

    身份提供商 username 资源属性
    Facebook id
    Google sub
    Login with Amazon user_id
    Sign in with Apple sub
    SAML 提供商 NameID
    OpenID Connect (OIDC) 提供者 sub
  • 当用户登录您的应用程序时,Amazon Cognito 必须能够更新映射的用户池属性。用户通过某个 IdP 登录时,Amazon Cognito 将使用来自该 IdP 的最新信息更新映射的属性。Amazon Cognito 将更新每个映射的属性,即使当前值已经与最新信息匹配也会更新。要确保 Amazon Cognito 可以更新属性,请检查以下要求:

    • 您从 IdP 映射的所有用户群体自定义属性都必须为可变的。您可以随时更新可变的自定义属性。相比之下,只有在首次创建用户配置文件时,才能为用户的不可变 自定义属性设置值。要在 Amazon Cognito 控制台中创建可变的自定义属性,请在 Sign-up experience(注册体验)选项卡中选择 Add custom attributes(添加自定义属性)时,为您添加的属性激活 Mutable(可变)复选框。或者,如果您使用 CreateUserPoolAPI 操作创建用户池,则可以将每个属性的Mutable参数设置为true。如果您的 IdP 发送映射的不可变属性的值,Amazon Cognito 会返回错误并登录失败。

    • 在应用程序的应用程序客户端设置中,映射的属性必须可写。您可以在 Amazon Cognito 控制台的 App clients (应用程序客户端) 页面中设置哪些属性为可写属性。或者,如果您使用 CreateUserPoolClient API 操作创建应用程序客户端,则可以将这些属性添加到 WriteAttributes 数组。如果您的 IdP 为映射的不可写属性发送值,则 Amazon Cognito 不会设置该属性值,而是继续进行身份验证。

  • 如果 IdP 属性包含多个值,则 Amazon Cognito 将所有值展平为单个以空格分隔的字符串,并对包含非字母数字字符(不包括“.”、“-”、“*”和“_”字符)的值进行 URL 格式编码。在您的应用程序中使用这些值之前,您必须解码并解析各个值。

指定适用于用户池的身份提供商属性映射(Amazon Web Services Management Console)

您可以使用 Amazon Web Services Management Console为您的用户池的 IdP 指定属性映射。

注意

只有当陈述存在于传入令牌中时,Amazon Cognito 才会将传入陈述映射到用户池属性。如果之前映射的声明不再存在于传入令牌中,则不会被删除或更改。如果您的应用程序需要映射已删除的声明,则可以使用预身份验证 Lambda 触发器在身份验证期间删除自定义属性,并允许从传入令牌重新填充这些属性。

指定社交 IdP 属性映射
  1. 登录 Amazon Cognito 控制台。如果出现提示,请输入 Amazon 凭证。

  2. 在导航窗格中,选择 User Pools(用户池),然后选择要编辑的用户池。

  3. 选择 Sign-in experience(登录体验)选项卡并找到 Federated sign-in(联合登录)。

  4. 选择 Add an identity provider(添加身份提供商),或者选择您已配置的 FacebookGoogleAmazonApple IdP。找到 Attribute mapping(属性映射),然后选择 Edit(编辑)。

    有关添加社交 IdP 的更多信息,请参阅向用户池添加社交身份提供商

  5. 对于需要映射的每个属性,请完成以下步骤:

    1. User pool attribute(用户池属性)列中选择属性。这是分配给您的用户池中用户配置文件的属性。自定义属性在标准属性之后列出。

    2. <provider> attribute(<provider> 属性)列中选择属性。这将是从提供商目录传递的属性。在下拉列表中提供来自社交服务提供商的已知属性。

    3. 要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。

  6. 选择 Save changes(保存更改)。

指定 SAML 提供商属性映射
  1. 登录 Amazon Cognito 控制台。如果出现提示,请输入 Amazon 凭证。

  2. 在导航窗格中,选择 User Pools(用户池),然后选择要编辑的用户池。

  3. 选择 Sign-in experience(登录体验)选项卡并找到 Federated sign-in(联合登录)。

  4. 选择 Add an identity provider(添加身份提供商),或者选择您已配置的 SAML IdP。找到 Attribute mapping(属性映射),然后选择 Edit(编辑)。有关添加 SAML IdP 的更多信息,请参阅向用户池添加 SAML 身份提供商

  5. 对于需要映射的每个属性,请完成以下步骤:

    1. User pool attribute(用户池属性)列中选择属性。这是分配给您的用户池中用户配置文件的属性。自定义属性在标准属性之后列出。

    2. SAML attribute(SAML 属性)列中选择属性。这将是从提供商目录传递的属性。

      您的 IdP 可能会提供示例 SAML 断言以供参考。有些 IdPs 使用简单的名称,例如email,而另一些则使用类似于 URL 格式的属性名称:

      http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
    3. 要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。

  6. 选择 Save changes(保存更改)。

指定适用于用户池的身份提供商属性映射(Amazon CLI 和 Amazon API)

使用以下命令为您的用户池指定 IdP 属性映射。

在提供商创建时指定属性映射
  • Amazon CLI: aws cognito-idp create-identity-provider

    带元数据文件的示例:aws cognito-idp create-identity-provider --user-pool-id <user_pool_id> --provider-name=SAML_provider_1 --provider-type SAML --provider-details file:///details.json --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    其中 details.json 包含:

    { "MetadataFile": "<SAML metadata XML>" }
    注意

    如果 <SAML metadata XML> 包含任何引号 ("),则必须对其进行转义 (\")。

    包含元数据 URL 的示例:

    aws cognito-idp create-identity-provider \ --user-pool-id us-east-1_EXAMPLE \ --provider-name=SAML_provider_1 \ --provider-type SAML \ --provider-details MetadataURL=https://myidp.example.com/saml/metadata \ --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • AmazonAPI: CreateIdentityProvider

指定现有 IdP 的属性映射
  • Amazon CLI: aws cognito-idp update-identity-provider

    例如:aws cognito-idp update-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • AmazonAPI: UpdateIdentityProvider

获取有关特定 IdP 的属性映射的信息
  • Amazon CLI: aws cognito-idp describe-identity-provider

    例如:aws cognito-idp describe-identity-provider --user-pool-id <user_pool_id> --provider-name <provider_name>

  • AmazonAPI: DescribeIdentityProvider