Skip to content
Ion
Docs Console Examples

CognitoUserPool

Reference doc for the `sst.aws.CognitoUserPool` component.

The CognitoUserPool component lets you add a Amazon Cognito User Pool to your app.

Create the user pool

sst.config.ts
const userPool = new sst.aws.CognitoUserPool("MyUserPool");

Login using email

sst.config.ts
new sst.aws.CognitoUserPool("MyUserPool", {
  usernames: ["email"]
});

Configure triggers

sst.config.ts
new sst.aws.CognitoUserPool("MyUserPool", {
  triggers: {
    preAuthentication: "src/preAuthentication.handler",
    postAuthentication: "src/postAuthentication.handler",
  },
});

Add a client

sst.config.ts
userPool.addClient("Web");

Constructor

new CognitoUserPool(name, args?, opts?)

Parameters

CognitoUserPoolArgs

aliases?

Type Input<Input<“email” | “phone” | “preferred_username”>[]>

Default User can only sign in with their username.

Configure the different ways a user can sign in besides using their username.

{
  aliases: ["email"]
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.userPool?

Type UserPoolArgs | (args: UserPoolArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Cognito User Pool resource.

triggers?

Type Input<Object>

Default No triggers

Configure triggers for this User Pool

{
  triggers: {
    preAuthentication: "src/preAuthentication.handler",
    postAuthentication: "src/postAuthentication.handler"
  }
}

triggers.createAuthChallenge?

Type string | FunctionArgs

Triggered after the user successfully responds to the previous challenge, and a new challenge needs to be created.

Takes the handler path or the function args.

triggers.customEmailSender?

Type string | FunctionArgs

Triggered during events like user sign-up, password recovery, email/phone number verification, and when an admin creates a user. Use this trigger to customize the email provider.

Takes the handler path or the function args.

triggers.customMessage?

Type string | FunctionArgs

Triggered during events like user sign-up, password recovery, email/phone number verification, and when an admin creates a user. Use this trigger to customize the message that is sent to your users.

Takes the handler path or the function args.

triggers.customSmsSender?

Type string | FunctionArgs

Triggered when an SMS message needs to be sent, such as for MFA or verification codes. Use this trigger to customize the SMS provider.

Takes the handler path or the function args.

triggers.defineAuthChallenge?

Type string | FunctionArgs

Triggered after each challenge response to determine the next action. Evaluates whether the user has completed the authentication process or if additional challenges are needed. ARN of the lambda function to name a custom challenge.

Takes the handler path or the function args.

triggers.postAuthentication?

Type string | FunctionArgs

Triggered after a successful authentication event. Use this to perform custom actions, such as logging or modifying user attributes, after the user is authenticated.

Takes the handler path or the function args.

triggers.postConfirmation?

Type string | FunctionArgs

Triggered after a user is successfully confirmed; sign-up or email/phone number verification. Use this to perform additional actions, like sending a welcome email or initializing user data, after user confirmation.

Takes the handler path or the function args.

triggers.preAuthentication?

Type string | FunctionArgs

Triggered before the authentication process begins. Use this to implement custom validation or checks (like checking if the user is banned) before continuing authentication.

Takes the handler path or the function args.

triggers.preSignUp?

Type string | FunctionArgs

Triggered before the user sign-up process completes. Use this to perform custom validation, auto-confirm users, or auto-verify attributes based on custom logic.

Takes the handler path or the function args.

triggers.preTokenGeneration?

Type string | FunctionArgs

Triggered before tokens are generated in the authentication process. Use this to customize or add claims to the tokens that will be generated and returned to the user.

Takes the handler path or the function args.

triggers.userMigration?

Type string | FunctionArgs

Triggered when a user attempts to sign in but does not exist in the current user pool. Use this to import and validate users from an existing user directory into the Cognito User Pool during sign-in.

Takes the handler path or the function args.

triggers.verifyAuthChallengeResponse?

Type string | FunctionArgs

Triggered after the user responds to a custom authentication challenge. Use this to verify the user’s response to the challenge and determine whether to continue authenticating the user.

Takes the handler path or the function args.

usernames?

Type Input<Input<“email” | “phone”>[]>

Default User can only sign in with their username.

Allow users to be able to sign up and sign in with an email addresses or phone number as their username.

{
  usernames: ["email"]
}

Properties

arn

Type Output<string>

The Cognito User Pool ARN.

id

Type Output<string>

The Cognito User Pool ID.

nodes

Type Object

The underlying resources this component creates.

nodes.userPool

Type UserPool

The Amazon Cognito User Pool.

SDK

Use the SDK in your runtime to interact with your infrastructure.

This is accessible through the Resource object in the SDK.

  • id string

    The Cognito User Pool ID.

Methods

addClient

addClient(name, args?)

Parameters

Returns CognitoUserPoolClient

Add a client to the user pool.

userPool.addClient("Web");

CognitoUserPoolClientArgs

transform?

Type Object

Transform how this component creates its underlying resources.

transform.client?

Type UserPoolClientArgs | (args: UserPoolClientArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Cognito User Pool client resource.