将 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_token
或id_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 属性映射
-
登录 Amazon Cognito 控制台
。如果出现提示,请输入 Amazon 凭证。 -
在导航窗格中,选择 User Pools(用户池),然后选择要编辑的用户池。
-
选择 Sign-in experience(登录体验)选项卡并找到 Federated sign-in(联合登录)。
-
选择 Add an identity provider(添加身份提供商),或者选择您已配置的 Facebook、Google、Amazon 或 Apple IdP。找到 Attribute mapping(属性映射),然后选择 Edit(编辑)。
有关添加社交 IdP 的更多信息,请参阅将社交身份提供者与用户池配合使用。
-
对于需要映射的每个属性,请完成以下步骤:
-
从 User pool attribute(用户池属性)列中选择属性。这是分配给您的用户池中用户配置文件的属性。自定义属性在标准属性之后列出。
-
从
<provider>
attribute(<provider> 属性)列中选择属性。这将是从提供商目录传递的属性。在下拉列表中提供来自社交服务提供商的已知属性。 -
要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。
-
-
选择 Save changes(保存更改)。
指定 SAML 提供商属性映射
-
登录 Amazon Cognito 控制台
。如果出现提示,请输入 Amazon 凭证。 -
在导航窗格中,选择 User Pools(用户池),然后选择要编辑的用户池。
-
选择 Sign-in experience(登录体验)选项卡并找到 Federated sign-in(联合登录)。
-
选择 Add an identity provider(添加身份提供商),或者选择您已配置的 SAML IdP。找到 Attribute mapping(属性映射),然后选择 Edit(编辑)。有关添加 SAML IdP 的更多信息,请参阅将 SAML 身份提供者与用户池配合使用。
-
对于需要映射的每个属性,请完成以下步骤:
-
从 User pool attribute(用户池属性)列中选择属性。这是分配给您的用户池中用户配置文件的属性。自定义属性在标准属性之后列出。
-
从 SAML attribute(SAML 属性)列中选择属性。这将是从提供商目录传递的属性。
您的 IdP 可能会提供示例 SAML 断言以供参考。一些 IdP 使用简单名称(如
email
),另一些则使用类似于下面 URL 格式的属性名称:http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。
-
-
选择 Save changes(保存更改)。
指定适用于用户池的身份提供商属性映射(Amazon CLI 和 Amazon API)
以下 CreateIdentityProvider 或 UpdateIdentityProvider 的请求正文按顺序将 SAML 提供者“MyIdP”属性 emailaddress
、birthdate
和 phone
映射到用户池属性 email
、birthdate
和 phone_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