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
Login using email
Configure triggers
Add Google identity provider
Add a client
Constructor
Parameters
-
name
string
-
args?
CognitoUserPoolArgs
-
opts?
ComponentResourceOptions
CognitoUserPoolArgs
advancedSecurity?
Type Input
<
“
audit
”
|
“
enforced
”
>
Default Advanced security is disabled.
Enable advanced security features.
Learn more about advanced security.
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.
mfa?
Type Input
<
“
on
”
|
“
optional
”
>
Default MFA is disabled.
Configure the multi-factor authentication (MFA) settings for the User Pool.
sms?
Type Input
<
Object
>
Default No SMS settings.
Configure the SMS settings for the User Pool.
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.
softwareToken?
Type Input
<
boolean
>
Default false
Enable software token MFA for the User Pool.
transform?
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.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.
Properties
arn
Type Output
<
string
>
The Cognito User Pool ARN.
id
Type Output
<
string
>
The Cognito User Pool ID.
nodes
nodes.userPool
Type Output
<
UserPool
>
The Amazon Cognito User Pool.
SDK
Use the SDK in your runtime to interact with your infrastructure.
Links
This is accessible through the Resource
object in the SDK.
-
id
string
The Cognito User Pool ID.
Methods
addClient
Parameters
Name of the client.name
string
- Configure the client.
Returns CognitoUserPoolClient
Add a client to the User Pool.
addIdentityProvider
Parameters
Name of the identity provider.name
string
- Configure the identity provider.
Returns CognitoIdentityProvider
Add a federated identity provider to the User Pool.
For example, add a GitHub (OIDC) identity provider.
Or add a Google identity provider.
static get
Parameters
The name of the component.name
string
The ID of the existing User Pool.userPoolID
Input
<
string
>
-
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
.
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.
CognitoIdentityProviderArgs
attributes?
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Define a mapping between identity provider attributes and user pool attributes.
details
Type Input
<
Record
<
string
, Input
<
string
>
>
>
Configure the identity provider details, including the scopes, URLs, and identifiers.
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.
Make sure to pass in provider.providerName
instead of hardcoding it to "MyProvider"
.
This ensures the client is created after the provider.
transform?
transform.client?
Type UserPoolClientArgs
|
(
args
:
UserPoolClientArgs
,
opts
:
ComponentResourceOptions
,
name
:
string
)
=>
void
Transform the Cognito User Pool client resource.