User Pool
Resource Overview
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
Event subscription wires (solid line) visualize and configure event subscription integrations between two resources.
The following resources can be subscribed to a User Pool:
- Function
Service Discovery
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:
- Function
- Edge Function
Configurable Properties
Logical ID
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: UserPool2
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 its place when the updated stack is deployed.
Allow Public Sign-Ups
Allows non-administrative users to sign up to this User Pool.
Auto-Verify Emails
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), a variable is added to the Function's environment containing the User Pool Client ID.
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.
Pre Sign-up
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.
Post Confirmation
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, allowing you to send custom messages to the user or perform other logic related to the newly-added user.
User Migration
Occurs when a user is signing in with a password, or is undertaking the forgot-password flow, and the user does not exist in the User Pool. This allows you to authenticate the user against your non-Cognito user database and return user attributes. Upon success, Cognito will create the user in the User Pool.
Pre Authentication
Occurs when a user attempts to sign in, providing you with the ability to perform custom validation to accept or deny a authentication request.
Post Authentication
Occurs after a user has successfully signed in, providing you with the ability to add custom logic after the user has been authenticated.
Pre Token Generation
Occurs after a user has succesfully signed in but before token generation, providing you with the ability to customize identity token claims.
Custom Message
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.
Define Authentication Challenge
Associate a function with this event, along with Create Authentication Challenge and Verify Authentication Challenge Response, to implement a custom authentication flow. This function is invoked to initiate the authentication flow. It should return the next challenge name and whether the user is authenticated.
Create Authentication Challenge
Occurs after the Define Authentication Challenge function provides a custom challenge response, providing you the opportunity to generate the challenge.
Verify Authentication Challenge Response
Occurs after the user responds to a custom challenge, allowing you to determine whether the response to the challenge was correct.
IAM Permissions
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
Environment Variables
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.
USER_POOL_ID
The unique identifier for the User Pool in Amazon Cognito
Example: us-east-1_Iqc12345
USER_POOL
The Amazon Resource Name of the Cognito User Pool
Example: arn:aws:cognito-idp:us-east-1:123412341234:userpool/us-east-1_Iqc12345
AWS SDK Code Example
Language-specific examples of AWS SDK calls using the environment variables discussed above.
Create a new user in a User Pool
// Load AWS SDK and create a new Cognito object
const AWS = require("aws-sdk");
const cognito = new AWS.CognitoIdentityServiceProvider();
const clientId = process.env.USER_POOL_CLIENT_ID; // supplied by Function service-discovery wire
exports.handler = async message => {
// Construct parameters for the signUp call
const params = {
ClientId: clientId,
Password: 'Password$123',
Username: 'NewUser_99',
UserAttributes: [
{
Name: 'email',
Value: 'test@email.com'
}
]
};
await cognito.signUp(params).promise();
console.log('User ' + params.Username + ', created');
}
import boto3
import os
# Create an Cognito Identity Provider client
cognito = boto3.client('cognito-idp')
user_pool_client_id = os.environ['USER_POOL_CLIENT_ID'] # Supplied by Function service-discovery wire
def handler(message, context):
# Add a new user to your User Pool
response = cognito.sign_up(
ClientId=user_pool_client_id,
Username='NewUser_99',
Password='Password$123',
UserAttributes=[
{
'Name':'email',
'Value':'test@email.com'
}
]
)
return response
Related AWS Documentation
AWS Documentation: AWS::Cognito::UserPool