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
allowSignup boolean Allow self sign up.
identityPoolOptions aws-cdk/aws-cognito-identitypool-alpha.IdentityPoolProps Configuration for the Identity Pool.
userPool aws-cdk-lib.aws_cognito.UserPool User provided Cognito UserPool.

allowSignupOptional
public readonly allowSignup: boolean;
  • Type: boolean
  • Default: false

Allow self sign up.


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-11-28