UserPoolProps Struct

Props for the UserPool construct.

Source: aws-cognito/lib/user-pool.ts
Type last changed: v2.224.0 · 13 Nov 2025

Example

new cognito.UserPool(this, 'myuserpool', {
  signInPolicy: {
    allowedFirstAuthFactors: { password: true, passkey: true },
  },
  passkeyRelyingPartyId: 'auth.example.com',
  passkeyUserVerification: cognito.PasskeyUserVerification.REQUIRED,
});

Properties

accountRecoveryAccountRecoveryaccount_recoveryAccountRecoveryaccountRecoveryAccountRecoveryAccountRecoveryAccountRecoveryAccountRecoveryAccountRecovery= AccountRecovery.PHONE_WITHOUT_MF…#

How will a user be able to recover their account?

default

Default: AccountRecovery.PHONE_WITHOUT_MFA_AND_EMAIL

advancedSecurityModeAdvancedSecurityModeadvanced_security_modeAdvancedSecurityModeadvancedSecurityModeAdvancedSecurityModeAdvancedSecurityModeAdvancedSecurityModeAdvancedSecurityModeAdvancedSecurityMode= no valuedeprecated#

Advanced Security Mode is deprecated due to user pool feature plans. Use StandardThreatProtectionMode and CustomThreatProtectionMode to set Thread Protection level.

autoVerifyAutoVerifiedAttrsauto_verifyAutoVerifiedAttrsautoVerifyAutoVerifiedAttrsAutoVerifyAutoVerifiedAttrsAutoVerifyAutoVerifiedAttrs= If `signInAlias` includes email …#

Attributes which Cognito will look to verify automatically upon user sign up.

EMAIL and PHONE are the only available options.

default

Default: If signInAlias includes email and/or phone, they will be included in autoVerifiedAttributes by default. If absent, no attributes will be auto-verified.

customAttributes{ [key: string]: ICustomAttribute }custom_attributestyping.Mapping[str, ICustomAttribute]customAttributesMap<String, ICustomAttribute>CustomAttributesIDictionary<string, ICustomAttribute>CustomAttributes*map[string]ICustomAttribute= No custom attributes.#

Define a set of custom attributes that can be configured for each user in the user pool.

customSenderKmsKeyIKeyRefcustom_sender_kms_keyIKeyRefcustomSenderKmsKeyIKeyRefCustomSenderKmsKeyIKeyRefCustomSenderKmsKeyIKeyRef= no key ID configured#

This key will be used to encrypt temporary passwords and authorization codes that Amazon Cognito generates.

customThreatProtectionModeCustomThreatProtectionModecustom_threat_protection_modeCustomThreatProtectionModecustomThreatProtectionModeCustomThreatProtectionModeCustomThreatProtectionModeCustomThreatProtectionModeCustomThreatProtectionModeCustomThreatProtectionMode= no value#

The Type of Threat Protection Enabled for Custom Authentication.

This feature only functions if your FeaturePlan is set to FeaturePlan.PLUS

deletionProtectionbooleandeletion_protectionbooldeletionProtectionBooleanDeletionProtectionboolDeletionProtection*bool= false#

Indicates whether the user pool should have deletion protection enabled.

deviceTrackingDeviceTrackingdevice_trackingDeviceTrackingdeviceTrackingDeviceTrackingDeviceTrackingDeviceTrackingDeviceTrackingDeviceTracking= see defaults on each property of…#

Device tracking settings.

default

Default: see defaults on each property of DeviceTracking.

emailUserPoolEmailemailUserPoolEmailemailUserPoolEmailEmailUserPoolEmailEmailUserPoolEmail= cognito will use the default ema…#

Email settings for a user pool.

default

Default: cognito will use the default email configuration

enableSmsRolebooleanenable_sms_roleboolenableSmsRoleBooleanEnableSmsRoleboolEnableSmsRole*bool= CDK will determine based on othe…#

Setting this would explicitly enable or disable SMS role creation.

When left unspecified, CDK will determine based on other properties if a role is needed or not.

default

Default: CDK will determine based on other properties of the user pool if an SMS role should be created or not.

featurePlanFeaturePlanfeature_planFeaturePlanfeaturePlanFeaturePlanFeaturePlanFeaturePlanFeaturePlanFeaturePlan= FeaturePlan.ESSENTIALS for a new…#

The user pool feature plan, or tier.

This parameter determines the eligibility of the user pool for features like managed login, access-token customization, and threat protection.

default

Default: FeaturePlan.ESSENTIALS for a newly created user pool; FeaturePlan.LITE otherwise

keepOriginalKeepOriginalAttrskeep_originalKeepOriginalAttrskeepOriginalKeepOriginalAttrsKeepOriginalKeepOriginalAttrsKeepOriginalKeepOriginalAttrs= Nothing is kept.#

Attributes which Cognito will look to handle changes to the value of your users' email address and phone number attributes.

EMAIL and PHONE are the only available options.

lambdaTriggersUserPoolTriggerslambda_triggersUserPoolTriggerslambdaTriggersUserPoolTriggersLambdaTriggersUserPoolTriggersLambdaTriggersUserPoolTriggers= No Lambda triggers.#

Lambda functions to use for supported Cognito triggers.

mfaMfamfaMfamfaMfaMfaMfaMfaMfa= Mfa.OFF#

Configure whether users of this user pool can or are required use MFA to sign in.

mfaMessagestringmfa_messagestrmfaMessageStringMfaMessagestringMfaMessage*string= 'Your authentication code is {##…#

The SMS message template sent during MFA verification.

Use '{####}' in the template where Cognito should insert the verification code.

default

Default: 'Your authentication code is {####}.'

mfaSecondFactorMfaSecondFactormfa_second_factorMfaSecondFactormfaSecondFactorMfaSecondFactorMfaSecondFactorMfaSecondFactorMfaSecondFactorMfaSecondFactor= { sms: true, otp: false, email: …#

Configure the MFA types that users can use in this user pool.

Ignored if mfa is set to OFF.

default

Default: { sms: true, otp: false, email: false }, if mfa is set to OPTIONAL or REQUIRED. { sms: false, otp: false, email:false }, otherwise

passkeyRelyingPartyIdstringpasskey_relying_party_idstrpasskeyRelyingPartyIdStringPasskeyRelyingPartyIdstringPasskeyRelyingPartyId*string= No authentication domain#

The authentication domain that passkey providers must use as a relying party (RP) in their configuration.

notes

Under the following conditions, the passkey relying party ID must be the fully-qualified domain name of your custom domain:

The user pool is configured for passkey authentication.
The user pool has a custom domain, whether or not it also has a prefix domain.
Your application performs authentication with managed login or the classic hosted UI.

passkeyUserVerificationPasskeyUserVerificationpasskey_user_verificationPasskeyUserVerificationpasskeyUserVerificationPasskeyUserVerificationPasskeyUserVerificationPasskeyUserVerificationPasskeyUserVerificationPasskeyUserVerification= Cognito default setting is Passk…#

Your user-pool treatment for MFA with a passkey.

You can override other MFA options and require passkey MFA, or you can set it as preferred. When passkey MFA is preferred, the hosted UI encourages users to register a passkey at sign-in.

default

Default: Cognito default setting is PasskeyUserVerification.PREFERRED

passwordPolicyPasswordPolicypassword_policyPasswordPolicypasswordPolicyPasswordPolicyPasswordPolicyPasswordPolicyPasswordPolicyPasswordPolicy= see defaults on each property of…#

Password policy for this user pool.

default

Default: see defaults on each property of PasswordPolicy.

removalPolicyRemovalPolicyremoval_policyRemovalPolicyremovalPolicyRemovalPolicyRemovalPolicyRemovalPolicyRemovalPolicyRemovalPolicy= RemovalPolicy.RETAIN#

Policy to apply when the user pool is removed from the stack.

selfSignUpEnabledbooleanself_sign_up_enabledboolselfSignUpEnabledBooleanSelfSignUpEnabledboolSelfSignUpEnabled*bool= false#

Whether self sign-up should be enabled.

To configure self sign-up configuration use the userVerification property.

signInAliasesSignInAliasessign_in_aliasesSignInAliasessignInAliasesSignInAliasesSignInAliasesSignInAliasesSignInAliasesSignInAliases= { username: true }#

Methods in which a user registers or signs in to a user pool.

notes

Allows either username with aliases OR sign in with email, phone, or both.

Read the sections on usernames and aliases to learn more - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html

To match with 'Option 1' in the above link, with a verified email, this property should be set to { username: true, email: true }. To match with 'Option 2' in the above link with both a verified email and phone number, this property should be set to { email: true, phone: true }.

signInCaseSensitivebooleansign_in_case_sensitiveboolsignInCaseSensitiveBooleanSignInCaseSensitiveboolSignInCaseSensitive*bool= true#

Whether sign-in aliases should be evaluated with case sensitivity.

For example, when this option is set to false, users will be able to sign in using either MyUsername or myusername.

signInPolicySignInPolicysign_in_policySignInPolicysignInPolicySignInPolicySignInPolicySignInPolicySignInPolicySignInPolicy= see defaults on each property of…#

Sign-in policy for this user pool.

default

Default: see defaults on each property of SignInPolicy.

smsRoleIRoleRefsms_roleIRoleRefsmsRoleIRoleRefSmsRoleIRoleRefSmsRoleIRoleRef= a new IAM role is created.#

The IAM role that Cognito will assume while sending SMS messages.

smsRoleExternalIdstringsms_role_external_idstrsmsRoleExternalIdStringSmsRoleExternalIdstringSmsRoleExternalId*string= No external id will be configure…#

The 'ExternalId' that Cognito service must be using when assuming the `smsRole`, if the role is restricted with an 'sts:ExternalId' conditional.

Learn more about ExternalId here - https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html

This property will be ignored if smsRole is not specified.

default

Default: No external id will be configured.

snsRegionstringsns_regionstrsnsRegionStringSnsRegionstringSnsRegion*string= The same region as the user pool…#

The region to integrate with SNS to send SMS messages.

This property will do nothing if SMS configuration is not configured.

default

Default: The same region as the user pool, with a few exceptions - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-sms-settings.html#user-pool-sms-settings-first-time

standardAttributesStandardAttributesstandard_attributesStandardAttributesstandardAttributesStandardAttributesStandardAttributesStandardAttributesStandardAttributesStandardAttributes= All standard attributes are opti…#

The set of attributes that are required for every user in the user pool.

default

Default: All standard attributes are optional and mutable.

standardThreatProtectionModeStandardThreatProtectionModestandard_threat_protection_modeStandardThreatProtectionModestandardThreatProtectionModeStandardThreatProtectionModeStandardThreatProtectionModeStandardThreatProtectionModeStandardThreatProtectionModeStandardThreatProtectionMode= StandardThreatProtectionMode.NO_…#

The Type of Threat Protection Enabled for Standard Authentication.

This feature only functions if your FeaturePlan is set to FeaturePlan.PLUS

default

Default: StandardThreatProtectionMode.NO_ENFORCEMENT

userInvitationUserInvitationConfiguser_invitationUserInvitationConfiguserInvitationUserInvitationConfigUserInvitationUserInvitationConfigUserInvitationUserInvitationConfig= see defaults in UserInvitationCo…#

Configuration around admins signing up users into a user pool.

default

Default: see defaults in UserInvitationConfig.

userPoolNamestringuser_pool_namestruserPoolNameStringUserPoolNamestringUserPoolName*string= automatically generated name by …#

Name of the user pool.

default

Default: automatically generated name by CloudFormation at deploy time.

userVerificationUserVerificationConfiguser_verificationUserVerificationConfiguserVerificationUserVerificationConfigUserVerificationUserVerificationConfigUserVerificationUserVerificationConfig= see defaults in UserVerification…#

Configuration around users signing themselves up to the user pool.

Enable or disable self sign-up via the selfSignUpEnabled property.

default

Default: see defaults in UserVerificationConfig.

Used as props by

UserPool

UserPoolProps Struct ​

Example ​

Properties ​

Used as props by ​

UserPoolProps Struct

Example

Properties

Used as props by