@aws-cdk/aws-cognito
Advanced tools
This is a developer preview (public beta) module.
All classes with the
Cfnprefix in this module (CFN Resources) are auto-generated from CloudFormation. They are stable and safe to use.However, all other classes, i.e., higher level constructs, are under active development and subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
Amazon Cognito provides authentication, authorization, and user management for your web and mobile apps. Your users can sign in directly with a user name and password, or through a third party such as Facebook, Amazon, Google or Apple.
The two main components of Amazon Cognito are user pools and identity pools. User pools are user directories that provide sign-up and sign-in options for your app users. Identity pools enable you to grant your users access to other AWS services.
This module is part of the AWS Cloud Development Kit project.
User pools allow creating and managing your own directory of users that can sign up and sign in. They enable easy integration with social identity providers such as Facebook, Google, Amazon, Microsoft Active Directory, etc. through SAML.
Using the CDK, a new user pool can be created as part of the stack using the construct's constructor. You may specify
the userPoolName to give your own identifier to the user pool. If not, CloudFormation will generate a name.
new UserPool(this, 'myuserpool', {
userPoolName: 'myawesomeapp-userpool',
});
Users can either be signed up by the app's administrators or can sign themselves up. Once a user has signed up, their account needs to be confirmed. Cognito provides several ways to sign users up and confirm their accounts. Learn more about user sign up here.
When a user signs up, email and SMS messages are used to verify their account and contact methods. The following code snippet configures a user pool with properties relevant to these verification messages -
new UserPool(this, 'myuserpool', {
// ...
selfSignUpEnabled: true,
userVerification: {
emailSubject: 'Verify your email for our awesome app!',
emailBody: 'Hello {username}, Thanks for signing up to our awesome app! Your verification code is {####}',
emailStyle: VerificationEmailStyle.CODE,
smsMessage: 'Hello {username}, Thanks for signing up to our awesome app! Your verification code is {####}',
}
});
By default, self sign up is disabled. Learn more about email and SMS verification messages here.
Besides users signing themselves up, an administrator of any user pool can sign users up. The user then receives an invitation to join the user pool. The following code snippet configures a user pool with properties relevant to the invitation messages -
new UserPool(this, 'myuserpool', {
// ...
userInvitation: {
emailSubject: 'Invite to join our awesome app!',
emailBody: 'Hello {username}, you have been invited to join our awesome app! Your temporary password is {####}',
smsMessage: 'Your temporary password for our awesome app is {####}'
}
});
All email subjects, bodies and SMS messages for both invitation and verification support Cognito's message templating. Learn more about message templates here.
Users registering or signing in into your application can do so with multiple identifiers. There are 4 options available:
username: Allow signing in using the one time immutable user name that the user chose at the time of sign up.email: Allow signing in using the email address that is associated with the account.phone: Allow signing in using the phone number that is associated with the account.preferredUsername: Allow signing in with an alternate user name that the user can change at any time. However, this
is not available if the username option is not chosen.The following code sets up a user pool so that the user can sign in with either their username or their email address -
new UserPool(this, 'myuserpool', {
// ...
// ...
signInAliases: {
username: true,
email: true
},
});
User pools can either be configured so that user name is primary sign in form, but also allows for the other three to be used additionally; or it can be configured so that email and/or phone numbers are the only ways a user can register and sign in. Read more about this here.
To match with 'Option 1' in the above link, with a verified email, signInAliases 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 }.
Cognito recommends that email and phone number be automatically verified, if they are one of the sign in methods for
the user pool. Read more about that
here.
The CDK does this by default, when email and/or phone number are specified as part of signInAliases. This can be
overridden by specifying the autoVerify property.
The following code snippet sets up only email as a sign in alias, but both email and phone number to be auto-verified.
new UserPool(this, 'myuserpool', {
// ...
// ...
signInAliases: { username: true, email: true },
autoVerify: { email: true, phone: true }
});
Cognito sends various messages to its users via SMS, for different actions, ranging from account verification to
marketing. In order to send SMS messages, Cognito needs an IAM role that it can assume, with permissions that allow it
to send SMS messages. By default, CDK will create this IAM role but can also be explicily specified to an existing IAM
role using the smsRole property.
import { Role } from '@aws-cdk/aws-iam';
const poolSmsRole = new Role(this, 'userpoolsmsrole', { /* ... */ });
new UserPool(this, 'myuserpool', {
// ...
smsRole: poolSmsRole,
smsRoleExternalId: 'c87467be-4f34-11ea-b77f-2e728ce88125'
});
When the smsRole property is specified, the smsRoleExternalId may also be specified. The value of
smsRoleExternalId will be used as the sts:ExternalId when the Cognito service assumes the role. In turn, the role's
assume role policy should be configured to accept this value as the ExternalId. Learn more about ExternalId
here.
Any user pool that has been created outside of this stack, can be imported into the CDK app. Importing a user pool
allows for it to be used in other parts of the CDK app that reference an IUserPool. However, imported user pools have
limited configurability. As a rule of thumb, none of the properties that is are part of the
AWS::Cognito::UserPool
CloudFormation resource can be configured.
User pools can be imported either using their id via the UserPool.fromUserPoolId(), or by using their ARN, via the
UserPool.fromUserPoolArn() API.
const stack = new Stack(app, 'my-stack');
const awesomePool = UserPool.fromUserPoolId(stack, 'awesome-user-pool', 'us-east-1_oiuR12Abd');
const otherAwesomePool = UserPool.fromUserPoolArn(stack, 'other-awesome-user-pool',
'arn:aws:cognito-idp:eu-west-1:123456789012:userpool/us-east-1_mtRyYQ14D');
1.28.0 (2020-03-16)
computeEnvironments is now requiredallocationStrategy property was moved from ComputeEnvironmentProps to the ComputeResources interface, which is where it semantically belongs.getDataString was renamed to getResponseField.getData was renamed to getResponseFieldReference.catchErrorPattern was renamed to ignoreErrorCodesMatching. In addition, a few synth time validations were added when using this property. See Error Handling for details.policyStatements property was removed in favor of a required policy property. Refer to Execution Policy for more details.catchErrorPattern to ignoreErrorCodesMatching (#6553) (94599f8), closes #5873getData* to getResponseField* (#6556) (d5867b4), closes #5873computeEnvironments is now required for JobQueue (#6616) (0b6c865), closes #6615FAQs
The CDK Construct Library for AWS::Cognito
The npm package @aws-cdk/aws-cognito receives a total of 52,911 weekly downloads. As such, @aws-cdk/aws-cognito popularity was classified as popular.
We found that @aws-cdk/aws-cognito demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.
Security News
Research
Noxia, a new dark web bulletproof host, offers dirt cheap servers for Python, Node.js, Go, and Rust, enabling cybercriminals to distribute malware and execute supply chain attacks.
Company News
Socket safeguards companies from software supply chain attacks by detecting and preventing threats in open source code and empowering developers to secure their applications and critical services against malware and other security risks.