Associating an Amazon WAF web ACL with a user pool

Amazon WAF is a web application firewall. With an Amazon 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 Amazon WAF web ACLs, see Managing and using a web access control list (web ACL) in the Amazon WAF Developer Guide.

When you have an Amazon WAF web ACL associated with a user pool, Amazon Cognito forwards selected non-confidential headers and contents of requests from your users to Amazon WAF. Amazon 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 Amazon WAF web ACLs and Amazon Cognito

Amazon 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 Amazon WAF rules in the Amazon 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 Amazon Identity and Access Management (IAM) principal must have the following Amazon Cognito and Amazon WAF permissions. For information about Amazon WAF permissions, see Amazon WAF API permissions in the Amazon 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 Amazon Command Line Interface or an SDK, use AssociateWebACL from the Amazon WAF API. Amazon Cognito doesn't have a separate API operation that associates a web ACL.

Testing and logging Amazon WAF web ACLs

When you set a rule action to Count in your web ACL, Amazon 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 Amazon WAF protections in the Amazon WAF Developer Guide.

You can also configure Amazon 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 Amazon WAF Developer Guide.

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

Logging Amazon 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 Amazon WAF Developer Guide.