Things to know about mappings Specifying identity provider attribute mappings for your user pool (AWS Management Console)Specifying identity provider attribute mappings for your user pool (AWS CLI and AWS API)

Mapping IdP attributes to profiles and tokens

Identity provider (IdP) services, including Amazon Cognito, can typically record more information about a user. You might want to know what company they work for, how to contact them, and other identifying information. But the format that these attributes take has variations between providers. For example, set up three IdPs from three different vendors with your user pool and examine an example SAML assertion, ID token, or userInfo payload from each. One will represent the user's email address as email, another as emailaddress, and the third as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

A major benefit that comes from consolidation of IdPs with a user pool is the ability to map the variety of attribute names into a single OIDC token schema with consistent, predicable, shared attribute names. This way, your developers aren't required to maintain the logic for processing a complex variety of single sign-on events. This format consolidation is attribute mapping. User pool attribute mapping assigns IdP attribute names to the corresponding user pool attribute names. For example, you can configure your user pool to write the value of an emailaddress claim to the standard user pool attribute email.

Each user pool IdP has a separate attribute-mapping schema. To specify attribute mappings for your IdP, configure a user pool identity provider in the Amazon Cognito console, an AWS SDK, or the user pools REST API .

Things to know about mappings

Before you begin to set up user-attribute mapping, 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.
You can map identity provider (IdP) tokens to custom attributes in your user pool. Social providers present an access token, and OIDC providers present an access and ID token. To map a token, add a custom attribute with a maximum length of 2,048 characters, grant your app client write access to the attribute, and map access_token or id_token from the IdP to the custom attribute.
For each mapped user pool attribute, the maximum value length of 2,048 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. Amazon Cognito doesn't support mapping IdP tokens to custom attributes when the tokens are more than 2,048 characters long.

Amazon Cognito derives the username attribute in a federated user's profile from specific claims that your federated IdP passes, as shown in the following table. Amazon Cognito prepends this attribute value with the name of your IdP, for example MyOIDCIdP_[sub]. When you want your federated users to have an attribute that exactly matches an attribute in your external user directory, map that attribute to a Amazon Cognito sign-in attribute like preferred_username.

Identity Provider	`username` source attribute
Facebook	`id`
Google	`sub`
Login with Amazon	`user_id`
Sign in with Apple	`sub`
SAML providers	`NameID`
OpenID Connect (OIDC) providers	`sub`

When a user pool is case insensitive, Amazon Cognito converts the username source attribute to lowercase in federated users' automatically-generated usernames. The following is an example username for a case-sensitive user pool: MySAML_TestUser@example.com. The following is the same username for a case-insensitive user pool: MySAML_testuser@example.com.

In case-insensitive user pools, your Lambda triggers that process the username must account for this modification to any mixed-case claims for user name source attributes. To link your IdP to a user pool that has a different case-sensitivity setting than your current user pool, create a new user pool.
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. 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 menu. 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. If your IdP sends a value for a mapped immutable attribute, Amazon Cognito returns an error and sign-in fails.
- 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. If your IdP sends a value for a mapped non-writable attribute, Amazon Cognito doesn't set the attribute value and proceeds with authentication.
When IdP attributes contain multiple values, Amazon Cognito flattens all values into a single comma-delimited string and URL form-encodes the values containing non-alphanumeric characters (excluding the ‘.’, ‘-’, ‘*’, and ‘_’ characters). You must decode and parse the individual values before you use them in your app.

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.

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 repopulate from the incoming token.

To specify a social IdP attribute mapping

Sign in to the Amazon Cognito console. If prompted, enter your AWS credentials.
In the navigation pane, choose User Pools, and choose the user pool you want to edit.
Choose the Social and external providers menu.
Choose Add an identity provider, or choose the Facebook, Google, Amazon or Apple IdP you have configured. Locate Attribute mapping and choose Edit.

For more information about adding a social IdP, see Using social identity providers with a user pool.
For each attribute you need to map, complete the following steps:
1. Select an attribute from the User pool attribute column. This is the attribute that is assigned to the user profile in your user pool. Custom attributes are listed after standard attributes.
2. Select an attribute from the <provider> attribute column. This will be the attribute passed from the provider directory. Known attributes from the social provider are provided in a drop-down list.
3. To map additional attributes between your IdP and Amazon Cognito, choose Add another attribute.
Choose Save changes.

To specify a SAML provider attribute mapping

Sign in to the Amazon Cognito console. If prompted, enter your AWS credentials.
In the navigation pane, choose User Pools, and choose the user pool you want to edit.
Choose the Social and external providers menu.
Choose Add an identity provider, or choose the SAML IdP you have configured. Locate Attribute mapping, and choose Edit. For more information about adding a SAML IdP, see Using SAML identity providers with a user pool.
For each attribute you need to map, complete the following steps:
1. Select an attribute from the User pool attribute column. This is the attribute that is assigned to the user profile in your user pool. Custom attributes are listed after standard attributes.
2. Select an attribute from the SAML attribute column. This will be the attribute passed from the provider directory.
  
  Your IdP might offer sample SAML assertions for reference. Some IdPs use simple names, such as email, while others use URL-formatted attribute names similar to:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
3. To map additional attributes between your IdP and Amazon Cognito, choose Add another attribute.
Choose Save changes.

Specifying identity provider attribute mappings for your user pool (AWS CLI and AWS API)

The following request body for CreateIdentityProvider or UpdateIdentityProvider maps the SAML provider "MyIdP" attributes emailaddress, birthdate, and phone to the user pool attributes email, birthdate, and phone_number, in that order. This is a complete request body for a SAML 2.0 provider—your request body will vary depending on IdP type and specific details. The attribute mapping is in the AttributeMapping parameter.


{
   "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"
}

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/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 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

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

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

OIDC user pool IdP authentication flow

Linking federated users