本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
将 IdP 属性映射到配置文件和令牌
身份提供商 (IdP) 服务,包括 Amazon Cognito,通常可以记录有关用户的更多信息。您可能想知道他们在哪家公司工作、如何联系他们以及其他识别信息。但是这些属性采用的格式因提供者而异。例如,使用您的用户池设置 IdPs 来自三个不同供应商的三个供应商,并检查每个供应商的示例SAML断言、ID 令牌或userInfo
有效负载。一个将用户的电子邮件地址表示为email
,另一个表示为emailaddress
,第三个表示为http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
。
IdPs 与用户池整合带来的一个主要好处是,能够将各种属性名称映射到具有一致、可预测的共享属性名称的单个OIDC令牌架构中。这样,您的开发人员就无需维护处理各种复杂单点登录事件的逻辑。这种格式合并是属性映射。用户池属性映射将 IdP 属性名称分配给相应的用户池属性名称。例如,您可以将用户池配置为将emailaddress
声明的值写入标准用户池属性email
。
每个用户池 IdP 都有单独的属性映射架构。要为您的 IdP 指定属性映射,请在 Amazon Cognito 控制台、 AWS 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 必须能够更新映射的用户池属性。用户通过某个 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并对包含非字母数字字符(不包括 ''、'、' 和
.
'' 字符)的值进行形式编码。-
*
_
在您的应用程序中使用这些值之前,您必须解码并解析各个值。
指定适用于用户池的身份提供商属性映射(AWS Management Console)
您可以使用为您的用户 AWS Management Console 池的 IdP 指定属性映射。
注意
只有当陈述存在于传入令牌中时,Amazon Cognito 才会将传入陈述映射到用户池属性。如果之前映射的声明不再存在于传入令牌中,则不会被删除或更改。如果您的应用程序需要映射已删除的声明,则可以使用预身份验证 Lambda 触发器在身份验证期间删除自定义属性,并允许从传入令牌重新填充这些属性。
指定社交 IdP 属性映射
-
登录 Amazon Cognito 控制台
。如果出现提示,请输入您的 AWS 凭据。 -
在导航窗格中,选择 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>
属性列。这将是从提供商目录传递的属性。在下拉列表中提供来自社交服务提供商的已知属性。 -
要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。
-
-
选择 Save changes(保存更改)。
指定SAML提供者属性映射
-
登录 Amazon Cognito 控制台
。如果出现提示,请输入您的 AWS 凭据。 -
在导航窗格中,选择 User Pools(用户池),然后选择要编辑的用户池。
-
选择 Sign-in experience(登录体验)选项卡并找到 Federated sign-in(联合登录)。
-
选择添加身份提供商,或选择您配置的 SAML IdP。找到 Attribute mapping(属性映射),然后选择 Edit(编辑)。有关添加 SAML IdP 的更多信息,请参阅。在用户池中使用SAML身份提供商
-
对于需要映射的每个属性,请完成以下步骤:
-
从 User pool attribute(用户池属性)列中选择属性。这是分配给您的用户池中用户配置文件的属性。自定义属性在标准属性之后列出。
-
从属性列中选择一个SAML属性。这将是从提供商目录传递的属性。
您的 IdP 可能会提供示例SAML断言以供参考。有些 IdPs 使用简单的名称,例如
email
,而另一些则使用类似于URL以下内容的格式化属性名称:http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
要在 IdP 和 Amazon Cognito 之间映射其它属性,请选择 Add another attribute(添加其它属性)。
-
-
选择 Save changes(保存更改)。
为用户池指定身份提供商属性映射(AWS CLI 和 AWS API)
以下请求正文按顺序将SAML提供者 “MyIdP” 属性emailaddress
birthdate
、、和UpdateIdentityProvider映射phone
到用户池属性email
birthdate
phone_number
、和。CreateIdentityProvider这是 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 属性映射。
在提供商创建时指定属性映射
-
AWS 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 的属性映射
-
AWS 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 的属性映射的信息
-
AWS 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