cognito-hooks-go

command module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 9 Imported by: 0

README

Cognito Hooks

An AWS Lambda function for Amazon Cognito user pool triggers. Rego policies you write make each hook's decisions, so you can change who may sign up without changing code.

The easiest way to deploy it is the terraform-aws-cognito-hooks module.

Hooks

Hook What it does
PreSignUp Allows or denies each sign-up and sets Cognito's auto-confirm and auto-verify flags. Can check the address with SendGrid first.
PostConfirmation Replaces the password of each user who confirms their sign-up or resets their password with a random one, for passwordless-only user pools.
PreAuthentication Runs at each sign-in and carries out the features you enable. Opt-in password rotation replaces a password the hooks haven't replaced since a cutoff time with a random one, so passwords exposed before then stop working.

One binary serves every hook; each function enables the hooks it handles.

Features

  • Policy-driven actions. Allow, deny, or auto-confirm by email domain, app client, trigger, user attribute, or client metadata. Policies return named actions (signup.allow, password.skip, ...), so hooks can gain actions without breaking existing policies.
  • Email verification with the SendGrid Email Address Validation API: deny undeliverable and disposable addresses, with an allowlist of trusted domains.
  • Passwordless enforcement. Replace passwords with random ones on confirmation and after password resets, so only passwordless factors can sign in, and optionally replace existing users' passwords at their next sign-in after a cutoff, one user at a time.
  • Safe by default. Configuration and policies are checked at startup, a broken PreSignUp policy rejects sign-ups instead of letting them through, PreAuthentication's password rotation is off until enabled and rejects a sign-in rather than let an old password be checked, and logs mask email addresses.

How it works

Cognito calls the function with a trigger event. The function routes it to the hook for its trigger source, the hook evaluates your policy, and carries out the actions it returns:

package cognito_hook_presignup

import rego.v1

result := {"actions": actions}

actions contains "signup.allow"

# a denial wins over the allow
actions contains {"action": "signup.deny", "reason": "Sign-up is limited to example.com addresses."} if {
	not endswith(input.userAttributes.email, "@example.com")
}

A denial's reason is shown to the user. See policies for writing and testing policies, and examples/policies for tested examples.

Deploying

With Terraform
module "cognito_hooks" {
  source  = "cruxstack/cognito-hooks/aws"
  version = "~> 2.0" # module v2 runs v1 of this function

  presignup_hook_enabled        = true
  presignup_hook_policy_content = file("${path.module}/presignup.rego")
}
By hand
  1. Download bootstrap_linux_arm64.zip (or amd64) from the latest release, or build it with make build.

  2. Add your policy to the zip: zip bootstrap_linux_arm64.zip presignup.rego. (make package PRESIGNUP_POLICY=presignup.rego builds and zips in one step.)

  3. Create a Lambda function with the provided.al2023 runtime, the matching architecture, handler bootstrap, and a 5 second timeout. For PostConfirmation and PreAuthentication's password rotation, give its role the IAM permissions, and for password rotation create its DynamoDB rotation table.

  4. Set the environment variables:

    APP_PRESIGNUP_ENABLED=true
    APP_PRESIGNUP_POLICY_PATH=presignup.rego
    
  5. Allow cognito-idp.amazonaws.com to invoke the function, and set it as the user pool's PreSignUp (or PostConfirmation, or PreAuthentication) trigger.

Local development

Evaluate a policy against sample events, with no AWS access:

go run ./cmd/devtool eval \
  -presignup-policy examples/policies/presignup/domains.rego \
  -events examples/events/presignup.json

Run events through the whole function, with your .env. Passwords aren't changed unless you pass -live:

cp .env.example .env
make run

make help lists the other targets; CONTRIBUTING covers tests and conventions.

Documentation

Document Covers
PreSignUp The PreSignUp hook, its policy, and email verification.
PostConfirmation The PostConfirmation hook, its requirements, and its policy.
PreAuthentication The PreAuthentication hook, its policy, and its password rotation: the cutoff, the rotation table, and what is unverified.
Policies Writing and testing policies.
Configuration Environment variables, packaging, IAM, Lambda settings.
Architecture Packages, the request flow, failure handling, new hooks.
Upgrading to v1 Breaking changes from v0.

License

MIT

Documentation

Overview

Command bootstrap is the AWS Lambda function for Amazon Cognito user pool hooks (PreSignUp, PostConfirmation, and PreAuthentication). Build it for the provided.al2023 runtime:

GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -tags lambda.norpc -o bootstrap .

Directories

Path Synopsis
cmd
devtool command
Command devtool runs Cognito hook events locally.
Command devtool runs Cognito hook events locally.
internal
action
Package action decodes the actions a policy returns.
Package action decodes the actions a policy returns.
app
Package app wires the function together from its configuration.
Package app wires the function together from its configuration.
cognito
Package cognito holds what every hook shares about Amazon Cognito user pool trigger events.
Package cognito holds what every hook shares about Amazon Cognito user pool trigger events.
config
Package config reads the configuration from environment variables.
Package config reads the configuration from environment variables.
handler
Package handler is the Lambda entry point: it decodes a Cognito trigger event and routes it to the hook for its trigger source.
Package handler is the Lambda entry point: it decodes a Cognito trigger event and routes it to the hook for its trigger source.
logging
Package logging configures structured logging and masks personal data in log attributes.
Package logging configures structured logging and masks personal data in log attributes.
password
Package password generates random passwords that satisfy any Cognito password policy.
Package password generates random passwords that satisfy any Cognito password policy.
policy
Package policy compiles and evaluates the Rego policies that make each hook's decision.
Package policy compiles and evaluates the Rego policies that make each hook's decision.
postconfirmation
Package postconfirmation implements the PostConfirmation hook.
Package postconfirmation implements the PostConfirmation hook.
preauthentication
Package preauthentication implements the PreAuthentication hook.
Package preauthentication implements the PreAuthentication hook.
presignup
Package presignup implements the PreSignUp hook.
Package presignup implements the PreSignUp hook.
rotation
Package rotation records when the hooks last replaced each user's password.
Package rotation records when the hooks last replaced each user's password.
sendgrid
Package sendgrid is a minimal client for the SendGrid v3 Email Address Validation API.
Package sendgrid is a minimal client for the SendGrid v3 Email Address Validation API.
verify
Package verify checks whether an email address is likely to be deliverable.
Package verify checks whether an email address is likely to be deliverable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL