Specifying identity provider attribute mappings for your user pool
You can use the AWS Management Console, or the AWS CLI or API, to specify attribute mappings for the identity provider (IdP) of your user pool.
Things to know about mappings
Before using mappings, review the following important details:
-
When a federated user signs in to your application, a mapping must be present for each user pool attribute that your user pool requires. For example, if your user pool requires an
email
attribute for sign-up, map this attribute to its equivalent from the IdP. -
By default, mapped email addresses are unverified. You can't verify a mapped email address using a one-time code. Instead, map an attribute from your IdP to get the verification status. For example, Google and most OIDC providers include the
email_verified
attribute. -
For each mapped user pool attribute, the maximum value length (2048 characters) must be large enough for the value that Amazon Cognito obtains from the IdP. Otherwise, Amazon Cognito reports an error when users sign in to your application. If you map a custom attribute to an IdP token, set the length to 2048 characters.
-
Amazon Cognito derives the
username
attribute in a federated user's profile from specific claims that your federated IdP passes, as follows. Amazon Cognito prepends this attribute value with the name of your IdP. When you want your federated users to have an attribute that exactly matches an attribute in your third-party directory, map that attribute to an alternative Amazon Cognito attribute likepreferred_username
.Identity Provider username
source attributeFacebook id
Google sub
Login with Amazon user_id
Sign in with Apple sub
SAML providers NameID
OpenID Connect (OIDC) providers sub
-
Amazon Cognito must be able to update your mapped user pool attributes when users sign in to your application. When a user signs in through an IdP, Amazon Cognito updates the mapped attributes with the latest information from the IdP. Amazon Cognito updates each mapped attribute, even if its current value already matches the latest information. If Amazon Cognito can't update the attribute, it reports an error. To ensure that Amazon Cognito can update the attributes, check the following requirements:
-
All of the user pool custom attributes that you map from your IdP must be mutable. You can update mutable custom attributes at any time. By contrast, you can only set a value for a user's immutable custom attribute when you first create the user profile. To create a mutable custom attribute in the Amazon Cognito console, activate the Mutable checkbox for the attribute you add when you select Add custom attributes in the Sign-up experience tab. Or, if you create your user pool by using the CreateUserPool API operation, you can set the
Mutable
parameter for each of these attributes totrue
.
-
In the app client settings for your application, the mapped attributes must be writable. You can set which attributes are writable in the App clients page in the Amazon Cognito console. Or, if you create the app client by using the
CreateUserPoolClient
API operation, you can add these attributes to theWriteAttributes
array.
-
-
When IdP attributes contain multiple values, Amazon Cognito URL form encodes the values containing non-alphanumeric characters (excluding the ‘
.
’, ‘-
’, ‘*
’, and ‘_
’ characters). You must decode the values before you use them in your application.
Specifying identity provider attribute mappings for your user pool (AWS Management Console)
You can use the AWS Management Console to specify attribute mappings for the IdP your user pool.
Amazon Cognito will map incoming claims to user pool attributes only if the claims exist in the incoming token. If a previously mapped claim no longer exists in the incoming token, it won't be deleted or changed. If your application requires mapping of deleted claims, you can use the Pre-Authentication Lambda trigger to delete the custom attribute during authentication and allow these attributes to re-populate from the incoming token.
Specifying identity provider attribute mappings for your user pool (AWS CLI and AWS API)
Use the following commands to specify IdP attribute mappings for your user pool.
To specify attribute mappings at provider creation time
-
AWS CLI:
aws cognito-idp create-identity-provider
Example with metadata file:
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/emailaddressWhere
details.json
contains:{ "MetadataFile": "
<SAML metadata XML>
" }Note If the
<SAML metadata XML>
contains any quotations ("
), they must be escaped (\"
).Example with metadata 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 -
AWS API: CreateIdentityProvider
To specify attribute mappings for an existing IdP
-
AWS CLI:
aws cognito-idp update-identity-provider
Example:
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 -
AWS API: UpdateIdentityProvider
To get information about attribute mapping for a specific IdP
-
AWS CLI:
aws cognito-idp describe-identity-provider
Example:
aws cognito-idp describe-identity-provider --user-pool-id
<user_pool_id>
--provider-name<provider_name>
-
AWS API: DescribeIdentityProvider