Associating an Amazon WAF web ACL with a user pool - Amazon Cognito
Things to know about Amazon WAF web ACLs and Amazon CognitoAssociating a web ACL with your user poolTesting and logging Amazon WAF web ACLs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 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

  • Requests blocked by Amazon WAF do not count towards the request rate quota for any request type. The Amazon WAF handler is called before the API-level throttling handlers.

  • When you create a web ACL, a small amount of time passes before the web ACL has fully propagated and is available to Amazon Cognito. The propagation time can be from a few seconds to a number of minutes. Amazon WAF returns a WAFUnavailableEntityException when you attempt to associate a web ACL before it has fully propagated.

  • You can associate one web ACL with a user pool.

  • Your request might result in a payload that is larger than the limits of what Amazon WAF can inspect. See Oversize request component handling in the Amazon WAF Developer Guide to learn how to configure how Amazon WAF handles oversize requests from Amazon Cognito.

  • You can’t associate a web ACL that uses Amazon WAF Fraud Control account takeover prevention (ATP) with an Amazon Cognito user pool. You implement the ATP feature when you add the AWS-AWSManagedRulesATPRuleSet managed rule group. Before you associate it with a user pool, ensure that your web ACL doesn’t use this managed rule group.

  • When you have an Amazon WAF web ACL associated with a user pool, and a rule in your web ACL presents a CAPTCHA, this can cause an unrecoverable error in hosted UI TOTP registration. To create a rule that has a CAPTCHA action and doesn't affect hosted UI TOTP, see Configuring your Amazon WAF web ACL for hosted UI TOTP MFA.

Amazon WAF inspects requests to the following endpoints.

Hosted UI

Requests to all endpoints in the User pool federation endpoints and hosted UI reference.

Public API operations

Requests from your app to the Amazon Cognito API that don't use Amazon credentials to authorize. This includes API operations like InitiateAuth, RespondToAuthChallenge, and GetUser. The API operations that are in scope of Amazon WAF don't require authentication with Amazon credentials. They are unauthenticated, or authorized with a session string or access token. For more information, see Amazon Cognito user pools authenticated and unauthenticated API operations.

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.

Important

Your options to customize the error response depends on the way you make an API request.

  • You can customize the error code and response body of hosted UI requests. You can only present a CAPTCHA for your user to solve in the hosted UI.

  • For requests that you make with the Amazon Cognito user pools API, you can customize the response body of a request that receives a Block response. You can also specify a custom error code in the range 400–499.

  • The Amazon Command Line Interface (Amazon CLI) and the Amazon SDKs return a ForbiddenException error to requests that produce a Block or CAPTCHA response.

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 permissions. For information about Amazon WAF permissions, see Amazon WAF API permissions in the Amazon WAF Developer Guide.

  • cognito-idp:AssociateWebACL

  • cognito-idp:DisassociateWebACL

  • cognito-idp:GetWebACLForResource

  • cognito-idp:ListResourcesForWebACL

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

To activate Amazon WAF for your user pool and associate a web ACL

  1. Sign in to the Amazon Cognito console .

  2. In the navigation pane, choose User Pools, and choose the user pool you want to edit.

  3. Choose the User pool properties tab.

  4. Choose Edit next to Amazon WAF.

  5. Under Amazon WAF, select Use Amazon WAF with your user pool.

    Screenshot of the Amazon WAF dialog box with Use Amazon WAF with your user pool selected.

  6. Choose an Amazon WAF Web ACL that you already created, or choose Create web ACL in Amazon WAF to create one in a new Amazon WAF session in the Amazon Web Services Management Console.

  7. Choose Save changes.

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 aren't subject to the pricing for Amazon Cognito advanced security features. The security features of Amazon WAF complement Amazon Cognito advanced security features. 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.