Skip to content

API Reference

Constructs

UserIdentity

Creates a UserPool and Identity Pool with sane defaults configured intended for usage from a web client.

Initializers 

import { UserIdentity } from '@aws/pdk/identity'

new UserIdentity(scope: Construct, id: string, props?: UserIdentityProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props UserIdentityProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsOptional

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { UserIdentity } from '@aws/pdk/identity'

UserIdentity.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
identityPool aws-cdk/aws-cognito-identitypool-alpha.IdentityPool No description.
userPool aws-cdk-lib.aws_cognito.UserPool No description.
userPoolClient aws-cdk-lib.aws_cognito.UserPoolClient No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

identityPoolRequired 
public readonly identityPool: IdentityPool;
userPoolRequired 
public readonly userPool: UserPool;
  • Type: aws-cdk-lib.aws_cognito.UserPool
userPoolClientRequired 
public readonly userPoolClient: UserPoolClient;
  • Type: aws-cdk-lib.aws_cognito.UserPoolClient

UserPoolWithMfa

Configures a UserPool with MFA across SMS/TOTP using sane defaults.

Initializers 

import { UserPoolWithMfa } from '@aws/pdk/identity'

new UserPoolWithMfa(scope: Construct, id: string, props?: UserPoolWithMfaProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props UserPoolWithMfaProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsOptional

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addClient Add a new app client to this user pool.
addDomain Associate a domain to this user pool.
addResourceServer Add a new resource server to this user pool.
addTrigger Add a lambda trigger to a user pool operation.
grant Adds an IAM policy statement associated with this user pool to an IAM principal's policy.
registerIdentityProvider Register an identity provider with this user pool.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addClient 
public addClient(id: string, options?: UserPoolClientOptions): UserPoolClient

Add a new app client to this user pool.

idRequired
  • Type: string
optionsOptional
  • Type: aws-cdk-lib.aws_cognito.UserPoolClientOptions
addDomain 
public addDomain(id: string, options: UserPoolDomainOptions): UserPoolDomain

Associate a domain to this user pool.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_cognito.UserPoolDomainOptions
addResourceServer 
public addResourceServer(id: string, options: UserPoolResourceServerOptions): UserPoolResourceServer

Add a new resource server to this user pool.

idRequired
  • Type: string
optionsRequired
  • Type: aws-cdk-lib.aws_cognito.UserPoolResourceServerOptions
addTrigger 
public addTrigger(operation: UserPoolOperation, fn: IFunction, lambdaVersion?: LambdaVersion): void

Add a lambda trigger to a user pool operation.

https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html

operationRequired
  • Type: aws-cdk-lib.aws_cognito.UserPoolOperation
fnRequired
  • Type: aws-cdk-lib.aws_lambda.IFunction
lambdaVersionOptional
  • Type: aws-cdk-lib.aws_cognito.LambdaVersion
grant 
public grant(grantee: IGrantable, actions: string): Grant

Adds an IAM policy statement associated with this user pool to an IAM principal's policy.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
actionsRequired
  • Type: string
registerIdentityProvider 
public registerIdentityProvider(provider: IUserPoolIdentityProvider): void

Register an identity provider with this user pool.

providerRequired
  • Type: aws-cdk-lib.aws_cognito.IUserPoolIdentityProvider

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
fromUserPoolArn Import an existing user pool based on its ARN.
fromUserPoolId Import an existing user pool based on its id.
isConstruct 
import { UserPoolWithMfa } from '@aws/pdk/identity'

UserPoolWithMfa.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { UserPoolWithMfa } from '@aws/pdk/identity'

UserPoolWithMfa.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { UserPoolWithMfa } from '@aws/pdk/identity'

UserPoolWithMfa.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromUserPoolArn 
import { UserPoolWithMfa } from '@aws/pdk/identity'

UserPoolWithMfa.fromUserPoolArn(scope: Construct, id: string, userPoolArn: string)

Import an existing user pool based on its ARN.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
userPoolArnRequired
  • Type: string
fromUserPoolId 
import { UserPoolWithMfa } from '@aws/pdk/identity'

UserPoolWithMfa.fromUserPoolId(scope: Construct, id: string, userPoolId: string)

Import an existing user pool based on its id.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
userPoolIdRequired
  • Type: string

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
identityProviders aws-cdk-lib.aws_cognito.IUserPoolIdentityProvider[] Get all identity providers registered with this user pool.
userPoolArn string The ARN of the user pool.
userPoolId string The physical ID of this user pool resource.
userPoolProviderName string User pool provider name.
userPoolProviderUrl string User pool provider URL.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

identityProvidersRequired 
public readonly identityProviders: IUserPoolIdentityProvider[];
  • Type: aws-cdk-lib.aws_cognito.IUserPoolIdentityProvider[]

Get all identity providers registered with this user pool.

userPoolArnRequired 
public readonly userPoolArn: string;
  • Type: string

The ARN of the user pool.

userPoolIdRequired 
public readonly userPoolId: string;
  • Type: string

The physical ID of this user pool resource.

userPoolProviderNameRequired 
public readonly userPoolProviderName: string;
  • Type: string

User pool provider name.

userPoolProviderUrlRequired 
public readonly userPoolProviderUrl: string;
  • Type: string

User pool provider URL.

Structs

UserIdentityProps

Properties which configures the Identity Pool.

Initializer 

import { UserIdentityProps } from '@aws/pdk/identity'

const userIdentityProps: UserIdentityProps = { ... }

Properties

Name Type Description
identityPoolOptions aws-cdk/aws-cognito-identitypool-alpha.IdentityPoolProps Configuration for the Identity Pool.
userPool aws-cdk-lib.aws_cognito.UserPool User provided Cognito UserPool.
identityPoolOptionsOptional 
public readonly identityPoolOptions: IdentityPoolProps;

Configuration for the Identity Pool.

userPoolOptional 
public readonly userPool: UserPool;
  • Type: aws-cdk-lib.aws_cognito.UserPool
  • Default: a userpool with mfa will be created.

User provided Cognito UserPool.

UserPoolWithMfaProps

UserPoolWithMfa props.

Initializer 

import { UserPoolWithMfaProps } from '@aws/pdk/identity'

const userPoolWithMfaProps: UserPoolWithMfaProps = { ... }

Properties

Name Type Description
accountRecovery aws-cdk-lib.aws_cognito.AccountRecovery How will a user be able to recover their account?
advancedSecurityMode aws-cdk-lib.aws_cognito.AdvancedSecurityMode The user pool's Advanced Security Mode.
autoVerify aws-cdk-lib.aws_cognito.AutoVerifiedAttrs Attributes which Cognito will look to verify automatically upon user sign up.
customAttributes {[ key: string ]: aws-cdk-lib.aws_cognito.ICustomAttribute} Define a set of custom attributes that can be configured for each user in the user pool.
customSenderKmsKey aws-cdk-lib.aws_kms.IKey This key will be used to encrypt temporary passwords and authorization codes that Amazon Cognito generates.
deletionProtection boolean Indicates whether the user pool should have deletion protection enabled.
deviceTracking aws-cdk-lib.aws_cognito.DeviceTracking Device tracking settings.
email aws-cdk-lib.aws_cognito.UserPoolEmail Email settings for a user pool.
enableSmsRole boolean Setting this would explicitly enable or disable SMS role creation.
keepOriginal aws-cdk-lib.aws_cognito.KeepOriginalAttrs Attributes which Cognito will look to handle changes to the value of your users' email address and phone number attributes.
lambdaTriggers aws-cdk-lib.aws_cognito.UserPoolTriggers Lambda functions to use for supported Cognito triggers.
mfa aws-cdk-lib.aws_cognito.Mfa Configure whether users of this user pool can or are required use MFA to sign in.
mfaMessage string The SMS message template sent during MFA verification.
mfaSecondFactor aws-cdk-lib.aws_cognito.MfaSecondFactor Configure the MFA types that users can use in this user pool.
passwordPolicy aws-cdk-lib.aws_cognito.PasswordPolicy Password policy for this user pool.
removalPolicy aws-cdk-lib.RemovalPolicy Policy to apply when the user pool is removed from the stack.
selfSignUpEnabled boolean Whether self sign-up should be enabled.
signInAliases aws-cdk-lib.aws_cognito.SignInAliases Methods in which a user registers or signs in to a user pool.
signInCaseSensitive boolean Whether sign-in aliases should be evaluated with case sensitivity.
smsRole aws-cdk-lib.aws_iam.IRole The IAM role that Cognito will assume while sending SMS messages.
smsRoleExternalId string The 'ExternalId' that Cognito service must be using when assuming the smsRole, if the role is restricted with an 'sts:ExternalId' conditional.
snsRegion string The region to integrate with SNS to send SMS messages.
standardAttributes aws-cdk-lib.aws_cognito.StandardAttributes The set of attributes that are required for every user in the user pool.
userInvitation aws-cdk-lib.aws_cognito.UserInvitationConfig Configuration around admins signing up users into a user pool.
userPoolName string Name of the user pool.
userVerification aws-cdk-lib.aws_cognito.UserVerificationConfig Configuration around users signing themselves up to the user pool.
accountRecoveryOptional 
public readonly accountRecovery: AccountRecovery;
  • Type: aws-cdk-lib.aws_cognito.AccountRecovery
  • Default: AccountRecovery.PHONE_WITHOUT_MFA_AND_EMAIL

How will a user be able to recover their account?

advancedSecurityModeOptional 
public readonly advancedSecurityMode: AdvancedSecurityMode;
  • Type: aws-cdk-lib.aws_cognito.AdvancedSecurityMode
  • Default: no value

The user pool's Advanced Security Mode.

autoVerifyOptional 
public readonly autoVerify: AutoVerifiedAttrs;
  • Type: aws-cdk-lib.aws_cognito.AutoVerifiedAttrs
  • Default: If signInAlias includes email and/or phone, they will be included in autoVerifiedAttributes by default. If absent, no attributes will be auto-verified.

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

EMAIL and PHONE are the only available options.

customAttributesOptional 
public readonly customAttributes: {[ key: string ]: ICustomAttribute};
  • Type: {[ key: string ]: aws-cdk-lib.aws_cognito.ICustomAttribute}
  • Default: No custom attributes.

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

customSenderKmsKeyOptional 
public readonly customSenderKmsKey: IKey;
  • Type: aws-cdk-lib.aws_kms.IKey
  • Default: no key ID configured

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

https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-custom-sender-triggers.html

deletionProtectionOptional 
public readonly deletionProtection: boolean;
  • Type: boolean
  • Default: false

Indicates whether the user pool should have deletion protection enabled.

deviceTrackingOptional 
public readonly deviceTracking: DeviceTracking;
  • Type: aws-cdk-lib.aws_cognito.DeviceTracking
  • Default: see defaults on each property of DeviceTracking.

Device tracking settings.

emailOptional 
public readonly email: UserPoolEmail;
  • Type: aws-cdk-lib.aws_cognito.UserPoolEmail
  • Default: cognito will use the default email configuration

Email settings for a user pool.

enableSmsRoleOptional 
public readonly enableSmsRole: boolean;
  • Type: boolean
  • Default: CDK will determine based on other properties of the user pool if an SMS role should be created or not.

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.

keepOriginalOptional 
public readonly keepOriginal: KeepOriginalAttrs;
  • Type: aws-cdk-lib.aws_cognito.KeepOriginalAttrs
  • Default: 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.

lambdaTriggersOptional 
public readonly lambdaTriggers: UserPoolTriggers;
  • Type: aws-cdk-lib.aws_cognito.UserPoolTriggers
  • Default: No Lambda triggers.

Lambda functions to use for supported Cognito triggers.

https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html

mfaOptional 
public readonly mfa: Mfa;
  • Type: aws-cdk-lib.aws_cognito.Mfa
  • Default: Mfa.OFF

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

mfaMessageOptional 
public readonly mfaMessage: string;
  • Type: string
  • Default: 'Your authentication code is {####}.'

The SMS message template sent during MFA verification.

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

mfaSecondFactorOptional 
public readonly mfaSecondFactor: MfaSecondFactor;
  • Type: aws-cdk-lib.aws_cognito.MfaSecondFactor
  • Default: { sms: true, otp: false }, if mfa is set to OPTIONAL or REQUIRED. { sms: false, otp: false }, otherwise

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

Ignored if mfa is set to OFF.

passwordPolicyOptional 
public readonly passwordPolicy: PasswordPolicy;
  • Type: aws-cdk-lib.aws_cognito.PasswordPolicy
  • Default: see defaults on each property of PasswordPolicy.

Password policy for this user pool.

removalPolicyOptional 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: RemovalPolicy.RETAIN

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

selfSignUpEnabledOptional 
public readonly selfSignUpEnabled: boolean;
  • Type: boolean
  • Default: false

Whether self sign-up should be enabled.

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

signInAliasesOptional 
public readonly signInAliases: SignInAliases;
  • Type: aws-cdk-lib.aws_cognito.SignInAliases
  • Default: { username: true }

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

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

signInCaseSensitiveOptional 
public readonly signInCaseSensitive: boolean;
  • Type: boolean
  • Default: 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.

smsRoleOptional 
public readonly smsRole: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: a new IAM role is created.

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

smsRoleExternalIdOptional 
public readonly smsRoleExternalId: string;
  • Type: string
  • Default: No external id will be configured.

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.

snsRegionOptional 
public readonly snsRegion: string;

The region to integrate with SNS to send SMS messages.

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

standardAttributesOptional 
public readonly standardAttributes: StandardAttributes;
  • Type: aws-cdk-lib.aws_cognito.StandardAttributes
  • Default: All standard attributes are optional and mutable.

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

Read more on attributes here - https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html

userInvitationOptional 
public readonly userInvitation: UserInvitationConfig;
  • Type: aws-cdk-lib.aws_cognito.UserInvitationConfig
  • Default: see defaults in UserInvitationConfig.

Configuration around admins signing up users into a user pool.

userPoolNameOptional 
public readonly userPoolName: string;
  • Type: string
  • Default: automatically generated name by CloudFormation at deploy time.

Name of the user pool.

userVerificationOptional 
public readonly userVerification: UserVerificationConfig;
  • Type: aws-cdk-lib.aws_cognito.UserVerificationConfig
  • Default: see defaults in UserVerificationConfig.

Configuration around users signing themselves up to the user pool.

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

Last update: 2024-05-08