将 IdP 属性映射到配置文件和令牌 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

将 IdP 属性映射到配置文件和令牌

身份提供者(IdP)服务(包括 Amazon Cognito)通常可以记录有关用户的更多信息。您可能想知道他们在哪家公司工作、如何联系他们以及其他可供识别的信息。但是,这些属性的格式在不同的提供者之间存在差异。例如,使用您的用户池设置来自三个不同供应者的三个 IdP,并检查每个 IdP 的示例 SAML 断言、ID 令牌或 userInfo 有效载荷。其中一个 IdP 将用户的电子邮件地址表示为 email,另一个表示为 emailaddress,第三个表示为 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

将 IdP 与用户池整合带来的一个主要好处是,能够将各种属性名称映射到具有一致、可预测的共享属性名称的单个 OIDC 令牌架构中。这样,您的开发人员就无需维护处理各种复杂单点登录事件的逻辑。这种格式整合就是属性映射。用户池属性映射将 IdP 属性名称分配给相应的用户池属性名称。例如,您可以将用户池配置为将 emailaddress 声明的值写入标准用户池属性 email

每个用户池 IdP 都有单独的属性映射架构。要为您的 IdP 指定属性映射,请在 Amazon Cognito 控制台、Amazon SDK 或用户池 REST API 中配置用户池身份提供者。

有关映射的需知信息

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

  • 当联合用户登录到您的应用程序时,您的用户群体需要的每个用户群体属性都必须存在一个映射。例如,如果您的用户群体需要 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
    通过 Apple 登录 sub
    SAML 提供商 NameID
    OpenID Connect (OIDC) 提供者 sub
  • 当用户池不区分大小写时,Amazon Cognito 会将联合用户自动生成的用户名中的用户名源属性转换为小写字母。以下是区分大小写的用户池的示例用户名:MySAML_TestUser@example.com。以下是不区分大小写的用户池的相同用户名:MySAML_testuser@example.com

    在不区分大小写的用户池中,处理用户名的 Lambda 触发器必须考虑到对任何混合大小写的声明进行的这种修改,以适应用户名称源属性。要将您的 IdP 链接到区分大小写设置与当前用户池不同的用户池,请创建一个新的用户池。

  • 当用户登录您的应用程序时,Amazon Cognito 必须能够更新映射的用户池属性。用户通过某个 IdP 登录时,Amazon Cognito 将使用来自该 IdP 的最新信息更新映射的属性。Amazon Cognito 将更新每个映射的属性,即使当前值已经与最新信息匹配也会更新。要确保 Amazon Cognito 可以更新属性,请检查以下要求:

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

以下 CreateIdentityProviderUpdateIdentityProvider 的请求正文按顺序将 SAML 提供者“MyIdP”属性 emailaddressbirthdatephone 映射到用户池属性 emailbirthdatephone_number。这是 SAML 2.0 提供者的完整请求正文,您的请求正文将因 IdP 类型和具体细节而有所不同。属性映射位于 AttributeMapping 参数中。

{ "AttributeMapping": { "email" : "emailaddress", "birthdate" : "birthdate", "phone_number" : "phone" }, "IdpIdentifiers": [ "IdP1", "pdxsaml" ], "ProviderDetails": { "IDPInit": "true", "IDPSignout": "true", "EncryptedResponses" : "true", "MetadataURL": "https://auth.example.com/sso/saml/metadata", "RequestSigningAlgorithm": "rsa-sha256" }, "ProviderName": "MyIdP", "ProviderType": "SAML", "UserPoolId": "us-west-2_EXAMPLE" }

使用以下命令为您的用户池指定 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
  • API/SDK: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

  • API/SDK: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>

  • API/SDK:DescribeIdentityProvider