Associating an AWS WAF web ACL with a user pool

AWS WAF is a web application firewall. With an AWS WAF web access control list (web ACL), you can protect your user pool from unwanted requests to your classic hosted UI and Amazon Cognito API service endpoints. A web ACL gives you fine-grained control over all of the HTTPS web requests that your user pool responds to. For more information about AWS WAF web ACLs, see Managing and using a web access control list (web ACL) in the AWS WAF Developer Guide.

When you have an AWS WAF web ACL associated with a user pool, Amazon Cognito forwards selected non-confidential headers and contents of requests from your users to AWS WAF. AWS WAF inspects the contents of the request, compares it to the rules that you specified in your web ACL, and returns a response to Amazon Cognito.

Things to know about AWS WAF web ACLs and Amazon Cognito

AWS WAF inspects requests to the following endpoints.

You can configure the rules in your web ACL with rule actions that Count, Allow, Block, or present a CAPTCHA in response to a request that matches a rule. For more information, see AWS WAF rules in the AWS WAF Developer Guide. Depending on the rule action, you can customize the response that Amazon Cognito returns to your users.

Associating a web ACL with your user pool

To work with a web ACL in your user pool, your AWS Identity and Access Management (IAM) principal must have the following Amazon Cognito and AWS WAF permissions. For information about AWS WAF permissions, see AWS WAF API permissions in the AWS WAF Developer Guide.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AllowWebACLUserPool",
			"Effect": "Allow",
			"Action": [
				"cognito-idp:ListResourcesForWebACL",
				"cognito-idp:GetWebACLForResource",
				"cognito-idp:AssociateWebACL"
			],
			"Resource": [
				"arn:aws:cognito-idp:*:123456789012:userpool/*"
			]
		},
		{
			"Sid": "AllowWebACLUserPoolWAFv2",
			"Effect": "Allow",
			"Action": [
				"wafv2:ListResourcesForWebACL",
				"wafv2:AssociateWebACL",
				"wafv2:DisassociateWebACL",
				"wafv2:GetWebACLForResource"
			],
			"Resource": "arn:aws:wafv2:*:123456789012:*/webacl/*/*"
		},
		{
			"Sid": "DisassociateWebACL1",
			"Effect": "Allow",
			"Action": "wafv2:DisassociateWebACL",
			"Resource": "*"
		},
		{
			"Sid": "DisassociateWebACL2",
			"Effect": "Allow",
			"Action": [
				"cognito-idp:DisassociateWebACL"
			],
			"Resource": [
				"arn:aws:cognito-idp:*:123456789012:userpool/*"
			]
		}
	]
}

Though you must grant IAM permissions, the listed actions are permission-only and don't correspond to an API operation.

To programmatically associate a web ACL with your user pool in the AWS Command Line Interface or an SDK, use AssociateWebACL from the AWS WAF API. Amazon Cognito doesn't have a separate API operation that associates a web ACL.

Testing and logging AWS WAF web ACLs

When you set a rule action to Count in your web ACL, AWS WAF adds the request to a count of requests that match the rule. To test a web ACL with your user pool, set rule actions to Count and consider the volume of requests that match each rule. For example, if a rule that you want to set to a Block action matches a large number of requests that you determine to be normal user traffic, you might need to reconfigure your rule. For more information, see Testing and tuning your AWS WAF protections in the AWS WAF Developer Guide.

You can also configure AWS WAF to log request headers to an Amazon CloudWatch Logs log group, an Amazon Simple Storage Service (Amazon S3) bucket, or an Amazon Data Firehose. You can identify the Amazon Cognito requests that you make with the user pools API by the x-amzn-cognito-client-id and x-amzn-cognito-operation-name. Hosted UI requests only include the x-amzn-cognito-client-id header. For more information, see Logging web ACL traffic in the AWS WAF Developer Guide.

AWS WAF web ACLs are available in all user pool feature plans. The security features of AWS WAF complement Amazon Cognito threat protection. You can activate both features in a user pool. AWS WAF bills separately for the inspection of user pool requests. For more information, see AWS WAF Pricing.

Logging AWS WAF request data is subject to additional billing by the service where you target your logs. For more information, see Pricing for logging web ACL traffic information in the AWS WAF Developer Guide.