Customizing the Uncustomizable
Cognito is a fully managed service — you can't modify its source code. But AWS recognized that every application has unique business logic that needs to run during authentication. The solution is Lambda Triggers: you attach a Lambda function to specific points in the Cognito lifecycle, and Cognito calls your function synchronously, waits for the response, and either proceeds or halts based on what your function returns.
This is a powerful pattern. It means you can extend a managed service with arbitrary custom logic without giving up the operational benefits of that managed service.
Key Triggers and Their Use Cases
1. Pre-Sign-Up
- When: Immediately before a new user record is saved to the User Pool.
- Input: The user's submitted attributes (email, phone, custom fields).
- Use Cases:
- Domain allowlisting: reject @gmail.com, accept only @yourclient.com.
- Auto-confirm users: set event['response']['autoConfirmUser'] = True to skip the email verification step (useful for internal tools or testing).
- Duplicate detection: check your own database before allowing sign-up.
- Failure mode: If your Lambda raises an exception, the sign-up is rejected and the user sees your error message. The account is never created.
2. Pre-Token Generation
- When: Right before Cognito mints the JWT tokens, after successful authentication.
- Input: The user's attributes and group memberships.
- Use Cases:
- Inject custom claims: look up the user's subscription tier in DynamoDB and add custom:tier: "gold" to the token.
- Suppress default claims: remove attributes from the token that you don't want exposed to clients.
- Add group-based permissions: translate Cognito group membership into application-specific roles.
- Why this matters: Your backend and frontend can read these custom claims directly from the JWT without an additional database call on every request.
3. Post-Confirmation
- When: After the user successfully verifies their email or phone number (i.e., they clicked the verification link or entered the OTP).
- Use Cases:
- Create a corresponding user profile in your application database (RDS, DynamoDB).
- Send a welcome email via SES.
- Trigger an onboarding workflow in Step Functions.
- Important: This trigger fires once per user, on first confirmation. It does not fire on subsequent logins.
4. User Migration
- When: A user attempts to sign in with credentials that don't exist in the User Pool.
- Use Cases: Seamlessly migrating users from a legacy authentication system to Cognito. Your Lambda checks the legacy system — if the credentials are valid there, it returns the user's attributes to Cognito, which creates the account on the fly. The user never knows a migration happened and never has to reset their password.
- Security note: This trigger only fires if the user is not found in Cognito. Once migrated, subsequent logins go through Cognito directly.
5. Custom Message
- When: Cognito is about to send a verification email, welcome message, or MFA code.
- Use Cases: Customize the email body and subject with your brand, language, and formatting. Without this trigger, Cognito sends generic, plaintext messages.
Trigger Failure Behavior
Lambda Triggers are synchronous — Cognito waits for your function to return. If your Lambda times out (default 3 seconds for Cognito triggers, configurable up to 5 seconds), Cognito treats it as a failure and the auth flow is interrupted. Keep trigger logic fast: do DynamoDB lookups, not complex multi-step workflows. For heavy work, use Post-Confirmation to kick off an async Step Functions execution.