Skip to content

Resource: awsCognitoUserPool

Provides a Cognito User Pool resource.

Example Usage

Basic configuration

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.cognitoUserPool.CognitoUserPool(this, "pool", {
  name: "mypool",
});

Enabling SMS and Software Token Multi-Factor Authentication

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.cognitoUserPool.CognitoUserPool(this, "example", {
  mfaConfiguration: "ON",
  smsAuthenticationMessage: "Your code is {####}",
  smsConfiguration: {
    externalId: "example",
    snsCallerArn: "${aws_iam_role.example.arn}",
    snsRegion: "us-east-1",
  },
  softwareTokenMfaConfiguration: {
    enabled: true,
  },
});

Using Account Recovery Setting

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.cognitoUserPool.CognitoUserPool(this, "test", {
  accountRecoverySetting: {
    recoveryMechanism: [
      {
        name: "verified_email",
        priority: 1,
      },
      {
        name: "verified_phone_number",
        priority: 2,
      },
    ],
  },
  name: "mypool",
});

Argument Reference

The following argument is required:

  • name - (Required) Name of the user pool.

The following arguments are optional:

  • accountRecoverySetting - (Optional) Configuration block to define which verified available method a user can use to recover their forgotten password. Detailed below.
  • adminCreateUserConfig - (Optional) Configuration block for creating a new user profile. Detailed below.
  • aliasAttributes - (Optional) Attributes supported as an alias for this user pool. Valid values: phoneNumber, email, or preferredUsername. Conflicts with usernameAttributes.
  • autoVerifiedAttributes - (Optional) Attributes to be auto-verified. Valid values: email, phoneNumber.
  • deletionProtection - (Optional) When active, DeletionProtection prevents accidental deletion of your user pool. Before you can delete a user pool that you have protected against deletion, you must deactivate this feature. Valid values are active and inactive, Default value is inactive.
  • deviceConfiguration - (Optional) Configuration block for the user pool's device tracking. Detailed below.
  • emailConfiguration - (Optional) Configuration block for configuring email. Detailed below.
  • emailVerificationMessage - (Optional) String representing the email verification message. Conflicts with verificationMessageTemplate configuration block emailMessage argument.
  • emailVerificationSubject - (Optional) String representing the email verification subject. Conflicts with verificationMessageTemplate configuration block emailSubject argument.
  • lambdaConfig - (Optional) Configuration block for the AWS Lambda triggers associated with the user pool. Detailed below.
  • mfaConfiguration - (Optional) Multi-Factor Authentication (MFA) configuration for the User Pool. Defaults of off. Valid values are off (MFA Tokens are not required), on (MFA is required for all users to sign in; requires at least one of smsConfiguration or softwareTokenMfaConfiguration to be configured), or optional (MFA Will be required only for individual users who have MFA Enabled; requires at least one of smsConfiguration or softwareTokenMfaConfiguration to be configured).
  • passwordPolicy - (Optional) Configuration blocked for information about the user pool password policy. Detailed below.
  • schema - (Optional) Configuration block for the schema attributes of a user pool. Detailed below. Schema attributes from the standard attribute set only need to be specified if they are different from the default configuration. Attributes can be added, but not modified or removed. Maximum of 50 attributes.
  • smsAuthenticationMessage - (Optional) String representing the SMS authentication message. The Message must contain the {####} placeholder, which will be replaced with the code.
  • smsConfiguration - (Optional) Configuration block for Short Message Service (SMS) settings. Detailed below. These settings apply to SMS user verification and SMS Multi-Factor Authentication (MFA). Due to Cognito API restrictions, the SMS configuration cannot be removed without recreating the Cognito User Pool. For user data safety, this resource will ignore the removal of this configuration by disabling drift detection. To force resource recreation after this configuration has been applied, see the taint command.
  • smsVerificationMessage - (Optional) String representing the SMS verification message. Conflicts with verificationMessageTemplate configuration block smsMessage argument.
  • softwareTokenMfaConfiguration - (Optional) Configuration block for software token Mult-Factor Authentication (MFA) settings. Detailed below.
  • tags - (Optional) Map of tags to assign to the User Pool. If configured with a provider defaultTags configuration block present, tags with matching keys will overwrite those defined at the provider-level.
  • userAttributeUpdateSettings - (Optional) Configuration block for user attribute update settings. Detailed below.
  • userPoolAddOns - (Optional) Configuration block for user pool add-ons to enable user pool advanced security mode features. Detailed below.
  • usernameAttributes - (Optional) Whether email addresses or phone numbers can be specified as usernames when a user signs up. Conflicts with aliasAttributes.
  • usernameConfiguration - (Optional) Configuration block for username configuration. Detailed below.
  • verificationMessageTemplate - (Optional) Configuration block for verification message templates. Detailed below.

accountRecoverySetting

  • recoveryMechanism - (Optional) List of Account Recovery Options of the following structure:
  • name - (Required) Recovery method for a user. Can be of the following: verifiedEmail, verifiedPhoneNumber, and adminOnly.
  • priority - (Required) Positive integer specifying priority of a method with 1 being the highest priority.

adminCreateUserConfig

  • allowAdminCreateUserOnly - (Optional) Set to True if only the administrator is allowed to create user profiles. Set to False if users can sign themselves up via an app.
  • inviteMessageTemplate - (Optional) Invite message template structure. Detailed below.

inviteMessageTemplate

  • emailMessage - (Optional) Message template for email messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively.
  • emailSubject - (Optional) Subject line for email messages.
  • smsMessage - (Optional) Message template for SMS messages. Must contain {username} and {####} placeholders, for username and temporary password, respectively.

deviceConfiguration

  • challengeRequiredOnNewDevice - (Optional) Whether a challenge is required on a new device. Only applicable to a new device.
  • deviceOnlyRememberedOnUserPrompt - (Optional) Whether a device is only remembered on user prompt. false equates to "Always" remember, true is "User Opt In," and not using a deviceConfiguration block is "No."

emailConfiguration

  • configurationSet - (Optional) Email configuration set name from SES.
  • emailSendingAccount - (Optional) Email delivery method to use. COGNITO_DEFAULT for the default email functionality built into Cognito or developer to use your Amazon SES configuration.
  • fromEmailAddress - (Optional) Sender’s email address or sender’s display name with their email address (e.g., john@exampleCom, johnSmith <john@exampleCom> or \"johnSmithPhD.\" <john@exampleCom>). Escaped double quotes are required around display names that contain certain characters as specified in RFC 5322.
  • replyToEmailAddress - (Optional) REPLY-TO email address.
  • sourceArn - (Optional) ARN of the SES verified email identity to use. Required if emailSendingAccount is set to developer.

lambdaConfig

  • createAuthChallenge - (Optional) ARN of the lambda creating an authentication challenge.
  • customMessage - (Optional) Custom Message AWS Lambda trigger.
  • defineAuthChallenge - (Optional) Defines the authentication challenge.
  • postAuthentication - (Optional) Post-authentication AWS Lambda trigger.
  • postConfirmation - (Optional) Post-confirmation AWS Lambda trigger.
  • preAuthentication - (Optional) Pre-authentication AWS Lambda trigger.
  • preSignUp - (Optional) Pre-registration AWS Lambda trigger.
  • preTokenGeneration - (Optional) Allow to customize identity token claims before token generation.
  • userMigration - (Optional) User migration Lambda config type.
  • verifyAuthChallengeResponse - (Optional) Verifies the authentication challenge response.
  • kmsKeyId - (Optional) The Amazon Resource Name of Key Management Service Customer master keys. Amazon Cognito uses the key to encrypt codes and temporary passwords sent to CustomEmailSender and CustomSMSSender.
  • customEmailSender - (Optional) A custom email sender AWS Lambda trigger. See custom_email_sender Below.
  • customSmsSender - (Optional) A custom SMS sender AWS Lambda trigger. See custom_sms_sender Below.

customEmailSender

  • lambdaArn - (Required) The Lambda Amazon Resource Name of the Lambda function that Amazon Cognito triggers to send email notifications to users.
  • lambdaVersion - (Required) The Lambda version represents the signature of the "request" attribute in the "event" information Amazon Cognito passes to your custom email Lambda function. The only supported value is V1_0.

customSmsSender

  • lambdaArn - (Required) The Lambda Amazon Resource Name of the Lambda function that Amazon Cognito triggers to send SMS notifications to users.
  • lambdaVersion - (Required) The Lambda version represents the signature of the "request" attribute in the "event" information Amazon Cognito passes to your custom SMS Lambda function. The only supported value is V1_0.

passwordPolicy

  • minimumLength - (Optional) Minimum length of the password policy that you have set.
  • requireLowercase - (Optional) Whether you have required users to use at least one lowercase letter in their password.
  • requireNumbers - (Optional) Whether you have required users to use at least one number in their password.
  • requireSymbols - (Optional) Whether you have required users to use at least one symbol in their password.
  • requireUppercase - (Optional) Whether you have required users to use at least one uppercase letter in their password.
  • temporaryPasswordValidityDays - (Optional) In the password policy you have set, refers to the number of days a temporary password is valid. If the user does not sign-in during this time, their password will need to be reset by an administrator.

schema

\~> NOTE: When defining an attributeDataType of string or number, the respective attribute constraints configuration block (e.g stringAttributeConstraints or numberAttributeConstraints) is required to prevent recreation of the Terraform resource. This requirement is true for both standard (e.g., name, email) and custom schema attributes.

  • attributeDataType - (Required) Attribute data type. Must be one of boolean, number, string, dateTime.
  • developerOnlyAttribute - (Optional) Whether the attribute type is developer only.
  • mutable - (Optional) Whether the attribute can be changed once it has been created.
  • name - (Required) Name of the attribute.
  • numberAttributeConstraints - (Required when attributeDataType is number) Configuration block for the constraints for an attribute of the number type. Detailed below.
  • required - (Optional) Whether a user pool attribute is required. If the attribute is required and the user does not provide a value, registration or sign-in will fail.
  • stringAttributeConstraints - (Required when attributeDataType is string) Constraints for an attribute of the string type. Detailed below.

schema: Defaults for Standard Attributes

The standard attributes have the following defaults. Note that attributes which match the default values are not stored in Terraform state when importing.

/*Provider bindings are generated by running cdktf get.
See https://cdk.tf/provider-generation for more details.*/
import * as aws from "./.gen/providers/aws";
new aws.cognitoUserPool.CognitoUserPool(this, "example", {
  schema: [
    {
      attributeDataType: "<appropriate type>",
      developerOnlyAttribute: false,
      mutable: true,
      name: "<name>",
      required: false,
      stringAttributeConstraints: {
        maxLength: 2048,
        minLength: 0,
      },
    },
  ],
});

numberAttributeConstraints

  • maxValue - (Optional) Maximum value of an attribute that is of the number data type.
  • minValue - (Optional) Minimum value of an attribute that is of the number data type.

stringAttributeConstraints

  • maxLength - (Optional) Maximum length of an attribute value of the string type.
  • minLength - (Optional) Minimum length of an attribute value of the string type.

smsConfiguration

  • externalId - (Required) External ID used in IAM role trust relationships. For more information about using external IDs, see How to Use an External ID When Granting Access to Your AWS Resources to a Third Party.
  • snsCallerArn - (Required) ARN of the Amazon SNS caller. This is usually the IAM role that you've given Cognito permission to assume.
  • snsRegion - (Optional) The AWS Region to use with Amazon SNS integration. You can choose the same Region as your user pool, or a supported Legacy Amazon SNS alternate Region. Amazon Cognito resources in the Asia Pacific (Seoul) AWS Region must use your Amazon SNS configuration in the Asia Pacific (Tokyo) Region. For more information, see SMS message settings for Amazon Cognito user pools.

softwareTokenMfaConfiguration

The following arguments are required in the softwareTokenMfaConfiguration configuration block:

  • enabled - (Required) Boolean whether to enable software token Multi-Factor (MFA) tokens, such as Time-based One-Time Password (TOTP). To disable software token MFA When smsConfiguration is not present, the mfaConfiguration argument must be set to off and the softwareTokenMfaConfiguration configuration block must be fully removed.

userAttributeUpdateSettings

  • attributesRequireVerificationBeforeUpdate - (Required) A list of attributes requiring verification before update. If set, the provided value(s) must also be set in autoVerifiedAttributes. Valid values: email, phoneNumber.

userPoolAddOns

  • advancedSecurityMode - (Required) Mode for advanced security, must be one of off, audit or enforced.

usernameConfiguration

  • caseSensitive - (Required) Whether username case sensitivity will be applied for all users in the user pool through Cognito APIs.

verificationMessageTemplate

  • defaultEmailOption - (Optional) Default email option. Must be either CONFIRM_WITH_CODE or CONFIRM_WITH_LINK. Defaults to CONFIRM_WITH_CODE.
  • emailMessage - (Optional) Email message template. Must contain the {####} placeholder. Conflicts with emailVerificationMessage argument.
  • emailMessageByLink - (Optional) Email message template for sending a confirmation link to the user, it must contain the {##clickHere##} placeholder.
  • emailSubject - (Optional) Subject line for the email message template. Conflicts with emailVerificationSubject argument.
  • emailSubjectByLink - (Optional) Subject line for the email message template for sending a confirmation link to the user.
  • smsMessage - (Optional) SMS message template. Must contain the {####} placeholder. Conflicts with smsVerificationMessage argument.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

  • arn - ARN of the user pool.
  • creationDate - Date the user pool was created.
  • customDomain - A custom domain name that you provide to Amazon Cognito. This parameter applies only if you use a custom domain to host the sign-up and sign-in pages for your application. For example: authExampleCom.
  • domain - Holds the domain prefix if the user pool has a domain associated with it.
  • endpoint - Endpoint name of the user pool. Example format: cognitoIdpRegionAmazonawsCom/xxxxYyyyy
  • estimatedNumberOfUsers - A number estimating the size of the user pool.
  • id - ID of the user pool.
  • lastModifiedDate - Date the user pool was last modified.
  • tagsAll - A map of tags assigned to the resource, including those inherited from the provider defaultTags configuration block.

Import

Cognito User Pools can be imported using the id, e.g.,

$ terraform import aws_cognito_user_pool.pool us-west-2_abc123