Specifying identity provider attribute mappings for your user pool - Amazon Cognito

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 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
  • 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 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 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 space-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
  1. Sign in to the Amazon Cognito console. If prompted, enter your AWS credentials.

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

  3. Choose the Sign-in experience tab and locate Federated sign-in.

  4. 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 Adding social identity providers to a user pool.

  5. 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.

  6. Choose Save changes.

To specify a SAML provider attribute mapping
  1. Sign in to the Amazon Cognito console. If prompted, enter your AWS credentials.

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

  3. Choose the Sign-in experience tab and locate Federated sign-in.

  4. 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 Adding SAML identity providers to a user pool.

  5. 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.

  6. Choose Save changes.

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