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 your user pool's identity providers.

Things to know about mappings

Before using mappings, review the following important details:

• A mapping must be present for each user pool attribute that's required when a user signs in to your application. For example, if your user pool requires an email attribute for sign-in, map this attribute to its equivalent from the identity provider.

• 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 identity provider 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 identity provider. Otherwise, Amazon Cognito throws an error when users sign in to your application. If you map a custom attribute to an identity provider token, set the length to 2048 characters.

• The username user pools attribute must be mapped only to specific attributes for the following identity providers:

  Identity Provider	Attribute to Map to username
  Facebook	id
  Google	sub
  Login with Amazon	user_id
  OpenID Connect (OIDC) providers	sub
  Sign in with Apple	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 identity provider, Amazon Cognito updates the mapped attributes with the latest information from the identity provider. 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 throws an error. To ensure that Amazon Cognito can update the attributes, check the following requirements:

  • The mapped user pool attributes must be mutable. Mutable attributes can be updated by app clients that have write permissions for those attributes. You can set user pool attributes as mutable when you define them in the Amazon Cognito console. Or, if you create your user pool by using the CreateUserPool API operation, you can set the Mutable parameter for each of these attributes to true.

  • 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 the WriteAttributes array.

• In the case of identity provider attributes containing multiple values, Amazon Cognito will URL form encode the values containing non-alphanumeric characters (excluding the ‘.’, ‘-’, ‘*’, and ‘_’ characters). You should decode the values prior to use 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 your user pool's identity providers.

Note

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.

To specify a social identity provider attribute mapping

1. Sign in to the Amazon Cognito console.

2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

3. Choose the Attribute mapping tab.

4. Choose the Facebook, Google, Amazon or Apple tab.

5. For each attribute you need to map, perform the following steps:

   1. Select the Capture check box.

   2. For User pool attribute, in the drop-down list, choose the user pool attribute you want to map to the social identity provider attribute.

   3. If you need more attributes, choose Add Facebook attribute (or Add Google attribute or Add Amazon attribute or Add Apple attribute) and perform the following steps:

      1. In the Facebook attribute (or Google attribute or Amazon attribute or Apple attribute) field, enter the name of the attribute to be mapped.

      2. In the User pool attribute field, choose the user pool attribute to map the social identity provider attribute to from the drop-down list.

   4. Choose Save changes.

To specify a SAML provider attribute mapping

1. Sign in to the Amazon Cognito console.

2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

3. Choose the Attribute mapping tab.

4. Choose the SAML tab.

5. Select the Capture box for all attributes for which you want to capture values. If you clear the Capture box for an attribute and save your changes, that attribute's mapping is removed.

6. Choose the identity provider from the drop-down list.

7. For each attribute you need to map, perform the following steps:

   1. Choose Add SAML attribute.

   2. In the SAML attribute field, enter the name of the SAML attribute to be mapped.

   3. In the User pool attribute field, choose the user pool attribute to map the SAML attribute to from the drop-down list.

8. Choose Save changes.

Specifying Identity Provider Attribute Mappings for Your User Pool (AWS CLI and AWS API)

Use the following commands to specify identity provider 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/emailaddress

  Where 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 identity provider

• 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 identity provider

• 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