A User Pool is a user directory stored in Amazon Cognito.
Implementing a User Pool in your stack gives you the ability to securely sign-up and authenticate users who intend to use your serverless applications. User Pools can be managed with the AWS SDK and accessed by Functions and Edge Functions to create, update, or delete the user profiles stored inside.
The events located in each User Pool resource allow you to offer a custom sign-up/sign-in process for your users and to better serve your application's needs. These events are covered in the User Pool Components & Implementation section below.
Event subscription wires (solid line) connect two or more resources and are required to accomplish certain tasks or improve performance within an application's flow.
The following resources can be subscribed to a User Pool:
Service discovery wires (dashed line) provide compute resources (Function, Edge Function) with the permissions and environment variables required to perform actions using cloud resources within the stack. This resource is on the receiving end of a service discovery wire originating from compute resources.
The following compute resources can use a service discovery wire to access a User Pool resource:
- Edge Function
Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.
The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in
template.yaml or while viewing a stack in Template View mode.
The Logical ID of all sub-resources associated with this User Pool will be prefixed with this value.
The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.
Default Logical ID Example:
IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in it's place when the updated stack is deployed.
Allow Public Sign-Ups
Allows non-administrative users to sign up to this User Pool.
Enabling this will automatically send email verifications when a user is signed-up to this User Pool.
User Pool Components & Implementation
Configuring User Pool Clients
User Pool Client resources (app client) can be configured to generate authentication tokens used to authorize a user for an application. When a User Pool Client resource is connected (using an event subscription wire) to a User Pool and the stack is deployed, a Client ID will be generated for an application to use to access the User Pool.
When you connect a Function resource to the User Pool Client with a service discovery wire (dashed wire), the Function will populate the User Pool Client ID to reference.
This value can be used directly in the Function's handler code since they'll be automatically configured as environment variables.
The screenshot above is an example of a Function resource connected to both a User Pool and a User Pool Client. The Function's environment variables are populated with the User Pool Client's identifier as well as the User Pool's identifier, which the Function requires in order to authorize users within the User Pool.
User Pool Events
The following User Pool Events can be attached to Function resources with an event subscription wire to invoke them when specific events occur.
Occurs just before a new user is added to the User Pool, providing you with the ability to perform custom validation to accept or deny a sign-up request.
Occurs after a new user is confirmed and added to the User Pool. This event contains the request with all the current attributes of the new user for you to perform custom messaging or logic to.
Occurs when a user attempts to sign in, providing you with the ability to perform custom validation to accept or deny a authentication request.
Occurs after a user has successfully signed in, providing you with the ability to add custom logic after the user has been authenticated.
Occurs before the User Pool sends email or phone verification messages, or multi-factor authentication (MFA) codes, providing you with the ability to customize those verification messages.
When connected by a service discovery wire (dashed wire), a Function or Edge Function will add the following IAM policy to its role and gain permission to access this resource.
- Statement: - Effect: Allow Action: - cognito-idp:Admin* - cognito-idp:DescribeIdentityProvider - cognito-idp:DescribeResourceServer - cognito-idp:DescribeUserPool - cognito-idp:DescribeUserPoolClient - cognito-idp:DescribeUserPoolDomain - cognito-idp:GetGroup - cognito-idp:ListGroups - cognito-idp:ListUserPoolClients - cognito-idp:ListUsers - cognito-idp:ListUsersInGroup - cognito-idp:UpdateGroup Resource: !GetAtt UserPool.Arn
When connected by a service discovery wire (dashed wire), a Function or Edge Function will automatically populate and reference the following environment variables in order to interact with this resource.
The unique identifier for the User Pool in Amazon Cognito
The Amazon Resource Name of the Cognito User Pool
Related AWS Documentation
AWS Documentation: AWS::Cognito::UserPool