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

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

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

有关映射的需知信息

在使用映射之前,请查看下面重要的详细信息:

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

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

  • 对于每个映射的用户池属性,最大值长度(2048 个字符)必须足够大,才能容纳 Amazon Cognito 从 IdP 处获取的值。否则,当用户登录到您的应用程序时,Amazon Cognito 会报告错误。如果您将自定义属性映射到 IdP 令牌,请将长度设置为 2048 个字符。

  • Amazon Cognito 从联合 IdP 传递的特定声明中派生出联合用户配置文件中的 username 属性,如下所示。Amazon Cognito 在此属性值前面加上 IdP 的名称。当您希望联合用户拥有与第三方目录中的属性完全匹配的属性时,请将该属性映射到另一个 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 无法更新属性,则会报告错误。要确保 Amazon Cognito 可以更新属性,请检查以下要求:

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

    • 在应用程序的应用程序客户端设置中,映射的属性必须可写。您可以在 Amazon Cognito 控制台的 App clients (应用程序客户端) 页面中设置哪些属性为可写属性。或者,如果您使用 CreateUserPoolClient API 操作创建应用程序客户端,则可以将这些属性添加到 WriteAttributes 数组。

  • 如果 IdP 属性包含多个值,Amazon Cognito URL 形式对包含非字母数字字符的值(不包括“.”、“-”、“*”和“_”字符)进行编码。在您的应用程序中使用这些值之前,您必须解码这些值。

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

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

注意

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

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

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

  3. 选择 Attribute mapping(属性映射)选项卡。

  4. 选择 FacebookGoogleAmazonApple 选项卡。

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

    1. 选中 Capture(截取)复选框。

    2. 对于 User pool attribute(用户池属性),在下拉列表中,选择要映射到社交 IdP 属性的用户池属性。

    3. 如果您需要更多属性,请选择 Add Facebook attribute(添加 Facebook 属性)[或者 Add Google attribute(添加 Google 属性)、Add Amazon attribute(添加 Amazon 属性)或 Add Apple attribute(添加 Apple 属性)] 并完成以下步骤:

      1. Facebook attribute(Facebook 属性)、Google attribute(Google 属性)、Amazon attribute(Amazon 属性)或 Apple attribute(Apple 属性)字段中,输入要映射的属性的名称。

      2. User pool attribute(用户池属性)下拉列表中,选择要将社交 IdP 属性映射到的用户池属性。

    4. 选择保存更改

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

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

  3. 选择 Attribute mapping(属性映射)选项卡。

  4. 选择 SAML 选项卡。

  5. 选中要捕获其值的所有属性对应的 Capture(截取)框。如果您清除某个属性的 Capture(截取)框并保存您的更改,Amazon Cognito 将删除该属性的映射。

  6. 从下拉列表中选择 IdP。

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

    1. 选择 Add SAML attribute(添加 SAML 属性)。

    2. SAML attribute(SAML 属性)字段中,输入要映射的 SAML 属性的名称。

    3. User pool attribute(用户池属性)字段中,从下拉列表中选择要将 SAML 属性映射到的用户池属性。

  8. 选择保存更改

New console
指定社交 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. 选择保存更改

指定 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 断言以供参考。一些 IdP 使用简单名称(如 email),另一些则使用类似于下面 URL 格式的属性名称:

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

  6. 选择保存更改

指定适用于用户池的身份提供商属性映射(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 <user_pool_id> --provider-name=SAML_provider_1 --provider-type SAML --provider-details MetadataURL=<metadata_url> --attribute-mapping email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • Amazon API: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

  • Amazon API: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>

  • Amazon API:DescribeIdentityProvider