Skip to content
SST
Blog Docs Console Examples
22K

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 Google identity provider

sst.config.ts
const GoogleClientId = new sst.Secret("GOOGLE_CLIENT_ID");
const GoogleClientSecret = new sst.Secret("GOOGLE_CLIENT_SECRET");


userPool.addIdentityProvider({
  type: "google",
  details: {
    authorize_scopes: "email profile",
    client_id: GoogleClientId.value,
    client_secret: GoogleClientSecret.value,
  },
  attributes: {
    email: "email",
    name: "name",
    username: "sub",
  },
});

Add a client

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

Constructor

new CognitoUserPool(name, args?, opts?)

Parameters

CognitoUserPoolArgs

advancedSecurity?

Type Input<“audit” | “enforced”>

Default Advanced security is disabled.

Enable advanced security features.

Learn more about advanced security.

{
  advancedSecurity: "enforced"
}

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"]
}

mfa?

Type Input<“on” | “optional”>

Default MFA is disabled.

Configure the multi-factor authentication (MFA) settings for the User Pool.

If you enable MFA using on or optional, you need to configure either sms or softwareToken as well.

{
  mfa: "on"
}

sms?

Type Input<Object>

Default No SMS settings.

Configure the SMS settings for the User Pool.

{
  sms: {
    externalId: "1234567890",
    snsCallerArn: "arn:aws:iam::1234567890:role/CognitoSnsCaller",
    snsRegion: "us-east-1",
  }
}

sms.externalId

Type Input<string>

The external ID used in IAM role trust relationships.

Learn more about external IDs.

sms.snsCallerArn

Type Input<string>

The ARN of the IAM role that Amazon Cognito can assume to access the Amazon SNS

sms.snsRegion?

Type Input<string>

The AWS Region that Amazon Cognito uses to send SMS messages.

smsAuthenticationMessage?

Type Input<string>

Default The default message template.

The message template for SMS messages sent to users who are being authenticated.

The template must include the {####} placeholder, which will be replaced with the verification code.

{
  smsAuthenticationMessage: "Your authentication code is {####}"
}

softwareToken?

Type Input<boolean>

Default false

Enable software token MFA for the User Pool.

{
  softwareToken: true
}

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 Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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

Takes the handler path, the function args, or a function ARN.

triggers.customEmailSender?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.customMessage?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.customSmsSender?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.defineAuthChallenge?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.kmsKey?

Type Input<string>

The ARN of the AWS KMS key used for encryption.

When customEmailSender or customSmsSender are configured, Cognito encrypts the verification code and temporary passwords before sending them to your Lambda functions.

triggers.postAuthentication?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.postConfirmation?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.preAuthentication?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.preSignUp?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.preTokenGeneration?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.preTokenGenerationVersion?

Type “v2” | “v1”

Default “v1”

The version of the preTokenGeneration trigger to use. Higher versions have access to more information that support new features.

triggers.userMigration?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

triggers.verifyAuthChallengeResponse?

Type Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

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, the function args, or a function ARN.

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 Output<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");

addIdentityProvider

addIdentityProvider(name, args)

Parameters

Returns CognitoIdentityProvider

Add a federated identity provider to the User Pool.

For example, add a GitHub (OIDC) identity provider.

sst.config.ts
const GithubClientId = new sst.Secret("GITHUB_CLIENT_ID");
const GithubClientSecret = new sst.Secret("GITHUB_CLIENT_SECRET");


userPool.addIdentityProvider("GitHub", {
  type: "oidc",
  details: {
     authorize_scopes: "read:user user:email",
     client_id: GithubClientId.value,
     client_secret: GithubClientSecret.value,
     oidc_issuer: "https://github.com/",
  },
  attributes: {
    email: "email",
    username: "sub",
  },
});

Or add a Google identity provider.

sst.config.ts
const GoogleClientId = new sst.Secret("GOOGLE_CLIENT_ID");
const GoogleClientSecret = new sst.Secret("GOOGLE_CLIENT_SECRET");


userPool.addIdentityProvider("Google", {
  type: "google",
  details: {
    authorize_scopes: "email profile",
    client_id: GoogleClientId.value,
    client_secret: GoogleClientSecret.value,
  },
  attributes: {
    email: "email",
    name: "name",
    username: "sub",
  },
});

static get

CognitoUserPool.get(name, userPoolID, opts?)

Parameters

  • name string

    The name of the component.

  • userPoolID Input<string>

    The ID of the existing User Pool.

  • opts? ComponentResourceOptions

Returns CognitoUserPool

Reference an existing User Pool with the given ID. This is useful when you create a User Pool in one stage and want to share it in another. It avoids having to create a new User Pool in the other stage.

Imagine you create a User Pool in the dev stage. And in your personal stage frank, instead of creating a new pool, you want to share the same pool from dev.

sst.config.ts
const userPool = $app.stage === "frank"
  ? sst.aws.CognitoUserPool.get("MyUserPool", "us-east-1_gcF5PjhQK")
  : new sst.aws.CognitoUserPool("MyUserPool");

Here us-east-1_gcF5PjhQK is the ID of the User Pool created in the dev stage. You can find this by outputting the User Pool ID in the dev stage.

sst.config.ts
return {
  userPool: userPool.id
};

CognitoIdentityProviderArgs

attributes?

Type Input<Record<string, Input<string>>>

Define a mapping between identity provider attributes and user pool attributes.

{
  email: "email",
  username: "sub"
}

details

Type Input<Record<string, Input<string>>>

Configure the identity provider details, including the scopes, URLs, and identifiers.

{
  authorize_scopes: "email profile",
  client_id: "your-client-id",
  client_secret: "your-client-secret"
}

transform?

Type Object

Transform how this component creates its underlying resources.

transform.identityProvider?

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

Transform the Cognito identity provider resource.

type

Type Input<“oidc” | “saml” | “google” | “facebook” | “apple” | “amazon”>

The type of identity provider.

CognitoUserPoolClientArgs

providers?

Type Input<Input<string>[]>

Default [“COGNITO”]

A list of identity providers that are supported for this client.

If you are using a federated identity provider.

sst.config.ts
const provider = userPool.addIdentityProvider("MyProvider", {
  type: "oidc",
  details: {
    authorize_scopes: "email profile",
    client_id: "your-client-id",
    client_secret: "your-client-secret"
  },
});

Make sure to pass in provider.providerName instead of hardcoding it to "MyProvider".

sst.config.ts
userPool.addClient("Web", {
  providers: [provider.providerName]
});

This ensures the client is created after the provider.

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.