Updating user pool and app client configuration - Amazon Cognito
Settings you can't changeSMS configurationUpdating a user pool with an AWS SDK, AWS CDK, or REST API

Updating user pool and app client configuration

When you want to change a setting in a user pool or app client, you can apply the update in the Amazon Cognito console with a few clicks. You navigate through the feature-based tabs in your user pool settings and update fields as described in other areas of this guide.

Many organizations manage their resources programmatically in AWS CloudFormation, applications built on the AWS SDKs or CDK, and other automation software. When this is your resource-management model, you must take extra care when you stage changes to your resources.

The API operations UpdateUserPool and UpdateUserPoolClient make updates to an existing user pool or app client. Each comes with a warning in the API Reference: If you don't provide a value for an attribute, Amazon Cognito sets it to its default value. When you submit an update request with just one parameter, Amazon Cognito sets that parameter to the value of your choosing and sets all others to a default value. This can reset configurations including your attribute schema, your Lambda triggers, and your email and SMS message configuration.

Additionally, some settings are locked in after you create your user pool or app client, and you can't change them unless you create a new resource.

Settings you can't change

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 Application-specific settings with 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 Working with user 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 Working with user 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 AWS SDK, AWS 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 AWS 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 AWS 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 AWS Cloud Development Kit (AWS CDK), Amazon Cognito user pools REST API and AWS 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 AWS CLI.

Alternately, run the following AWS 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