Updating user pool configuration - Amazon Cognito
SMS configurationUpdating a user pool with an Amazon SDK, Amazon CDK, or REST API
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Updating user pool configuration

To change the settings of Amazon Cognito user pools in the Amazon Web Services Management Console, navigate through the feature-based tabs in your user pool settings and update fields as described in other areas of this guide. You can't change some settings after you create a user pool. If you want to change the following settings, you must create a new user pool or app client.

User pool name

API parameter name: PoolName

The friendly name that you assigned to your user pool. To change the name of a user pool, create a new user pool.

Amazon Cognito user pool sign-in options

API parameter names: AliasAttributes and UsernameAttributes

The attributes that your users can pass as a user name when they sign in. When you create a user pool, you can choose to allow sign-in with user name, email address, phone number, or a preferred user name. To change user pool sign-in options, create a new user pool.

Make user name case sensitive

API parameter name: UsernameConfiguration

When you create a user name that matches another user name except for the letter case, Amazon Cognito can treat them as either the same user or as unique users. For more information, see User pool case sensitivity. To change case sensitivity, create a new user pool.

Client secret

API parameter name: GenerateSecret

When you create an app client, you can generate a client secret so that only trusted sources can make requests to your user pool. For more information, see User pool app clients. To change a client secret, create a new app client in the same user pool.

Required attributes

API parameter name: Schema

The attributes that your users must provide values for when they sign up, or when you create them. For more information, see User pool attributes. To change required attributes, create a new user pool.

Custom attributes

API parameter name: Schema

Attributes with custom names. You can change the value of a user's custom attribute, but you can't delete a custom attribute from your user pool. For more information, see User pool attributes. If you reach the maximum number of custom attributes and you want to modify the list, create a new user pool.

SMS configuration

After you activate SMS messages in your user pool, you can't deactivate them.

  • If you choose to configure SMS messages when you create a user pool, you can't deactivate SMS after you complete setup.

  • You can activate SMS messages in a user pool that you created, but after that you can't deactivate SMS.

  • Amazon Cognito can use SMS messages for user account invitation and recovery, attribute verification, and multi-factor authentication (MFA). After you activate SMS messages, you can turn SMS messages on or off for these functions at any time.

  • SMS message configuration includes an IAM role that you delegate to Amazon Cognito to send messages with Amazon SNS. You can change the assigned role at any time.

Updating a user pool with an Amazon SDK, Amazon CDK, or REST API

In the Amazon Cognito console, you can change your user pool settings one parameter at a time. For example, to add a Lambda trigger, you choose Add Lambda trigger and choose the function and trigger type. The Amazon Cognito user pools API is structured in a way that update operations for user pools and app clients require the full set of parameters for the user pool. However, the console transparently automates this update operation with your other user pool settings.

You might find at times that a change elsewhere in your Amazon Web Services account can cause updates to generate an error when they aren't related to the setting you want to change. A deleted Amazon SES identity or a change in an IAM permission for Amazon WAF, for example. If one of the current parameters is no longer valid, you can't update your settings until you fix it. When you encounter such an error, examine the error response and validate the setting that it mentions.

The Amazon Cloud Development Kit (Amazon CDK), Amazon Cognito user pools REST API and Amazon SDKs are tools for automation and programmatic configuration of Amazon Cognito resources. Requests with these tools must also, like the Amazon Cognito console, update a setting with a full resource configuration in the request body. At a high level, you must perform the following process.

  1. Capture the output from an operation that describes the configuration of your existing resource .

  2. Modify the output with your settings change.

  3. Send the modified configuration in an operation that updates your resource.

The following procedure updates your configuration with the UpdateUserPool API operation. The same approach, with different input fields, applies to UpdateUserPoolClient.

Important

If you don't provide values for existing parameters, Amazon Cognito sets them to default values. For example, when you have existing LambdaConfig and you submit an UpdateUserPool with an empty LambdaConfig, you delete the assignment of all Lambda functions to user pool triggers. Plan accordingly when you want to automate changes to your user pool configuration.

  1. Capture the existing state of your user pool with DescribeUserPool.

  2. Format the output of DescribeUserPool to match the request parameters of UpdateUserPool. Remove the following top-level fields and their child objects from the output JSON.

    • Arn

    • CreationDate

    • CustomDomain

    • Domain

    • EmailConfigurationFailure

    • EstimatedNumberOfUsers

    • Id

    • LastModifiedDate

    • Name

    • SchemaAttributes

    • SmsConfigurationFailure

    • Status

  3. Confirm that the resulting JSON matches the request parameters of UpdateUserPool.

  4. Modify any parameters that you want to change in the resulting JSON.

  5. Submit an UpdateUserPool API request with your modified JSON as the request input.

You can also use this modified DescribeUserPool output in the --cli-input-json parameter of update-user-pool in the Amazon CLI.

Alternately, run the following Amazon CLI command to generate JSON with blank values for the accepted input fields for update-user-pool. You can then populate these fields with the existing values from your user pool.

aws cognito-idp update-user-pool --generate-cli-skeleton --output json

Run the following command to generate the same JSON object for an app client.

aws cognito-idp update-user-pool-client --generate-cli-skeleton --output json