**Introducing a new console experience for AWS WAF** You can now use the updated experience to access AWS WAF functionality anywhere in the console. For more details, see [Working with the console](https://docs.aws.amazon.com/waf/latest/developerguide/working-with-console.html). # Token use in AWS WAF intelligent threat mitigation Tokens in intelligent threat mitigationNew section on AWS WAF tokens Understand how AWS WAF uses tokens for intelligent threat mitigation. This section explains what AWS WAF tokens do. AWS WAF tokens are an integral part of the enhanced protections offered by AWS WAF intelligent threat mitigation. A token, sometimes called a fingerprint, is a collection of information about a single client session that the client stores and provides with every web request that it sends. AWS WAF uses tokens to identify and separate malicious client sessions from legitimate sessions, even when both originate from a single IP address. Token use imposes costs that are negligible for legitimate users, but expensive at scale for botnets. AWS WAF uses tokens to support its browser and end user challenge functionality, which is provided by the application integration SDKs and by the rule actions Challenge and CAPTCHA. Additionally, tokens enable features of the AWS WAF Bot Control and account takeover prevention managed rule groups. AWS WAF creates, updates, and encrypts tokens for clients that successfully respond to silent challenges and CAPTCHA puzzles. When a client with a token sends a web request, it includes the encrypted token, and AWS WAF decrypts the token and verifies its contents. **Topics** + [ # How AWS WAF uses tokens ](waf-tokens-usage.md) + [ # AWS WAF token characteristics ](waf-tokens-details.md) + [ # Setting timestamp expiration and token immunity times in AWS WAF ](waf-tokens-immunity-times.md) + [ # Specifying token domains and domain lists in AWS WAF ](waf-tokens-domains.md) + [ # Types of token labels in AWS WAF ](waf-tokens-labeling.md) + [ # Blocking requests that don't have a valid AWS WAF token ](waf-tokens-block-missing-tokens.md) + [ # Required configuration for Application Load Balancers that are CloudFront origins ](waf-tokens-with-alb-and-cf.md) # How AWS WAF uses tokens How AWS WAF uses tokens This section explains how AWS WAF uses tokens. AWS WAF uses tokens to record and verify the following types of client session validation: + **CAPTCHA** – CAPTCHA puzzles help distinguish bots from human users. A CAPTCHA is run only by the CAPTCHA rule action. Upon successful completion of the puzzle, the CAPTCHA script updates the token's CAPTCHA timestamp. For more information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md). + **Challenge** – Challenges run silently to help distinguish regular client sessions from bot sessions and to make it more costly for bots to operate. When the challenge completes successfully, the challenge script automatically procures a new token from AWS WAF if needed, and then updates the token's challenge timestamp. AWS WAF runs challenges in the following situations: + **Application integration SDKs** – The application integration SDKs run inside your client application sessions and help ensure that login attempts are only allowed after the client has successfully responded to a challenge. For more information, see [Client application integrations in AWS WAF](waf-application-integration.md). + **Challenge rule action** – For more information, see [CAPTCHA and Challenge in AWS WAF](waf-captcha-and-challenge.md). + **CAPTCHA** – When a CAPTCHA interstitial runs, if the client doesn't have a token yet, the script automatically runs a challenge first, to verify the client session and to initialize the token. Tokens are required by many of the rules in the intelligent threat AWS Managed Rules rule groups. The rules use tokens to do things like distinguish between clients at the session level, to determine browser characteristics, and to understand the level of human interactivity on the application web page. These rule groups invoke AWS WAF token management, which applies token labeling that the rule groups then inspect. + **AWS WAF Fraud Control account creation fraud prevention (ACFP)** – The ACFP rules require web requests with valid tokens. For more information about the rules, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md). + **AWS WAF Fraud Control account takeover prevention (ATP)** – The ATP rules that prevent high volume and long lasting client sessions require web requests that have a valid token with an unexpired challenge timestamp. For more information, see [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md). + **AWS WAF Bot Control** – The targeted rules in this rule group place a limit on the number of web requests that a client can send without a valid token, and they use token session tracking for session-level monitoring and management. As needed, the rules apply the Challenge and CAPTCHA rule actions to enforce token acquisition and valid client behavior. For more information, see [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). # AWS WAF token characteristics Token characteristics Each token has the following characteristics: + The token is stored in a cookie named `aws-waf-token`. + The token is encrypted. + The token fingerprints the client session with a sticky granular identifier that contains the following information: + The timestamp of the client's latest successful response to a silent challenge. + The timestamp of the end user's latest successful response to a CAPTCHA. This is only present if you use CAPTCHA in your protections. + Additional information about the client and client behavior that can help separate your legitimate clients from unwanted traffic. The information includes various client identifiers and client-side signals that can be used to detect automated activities. The information gathered is non-unique and can't be mapped to an individual human being. + All tokens include data from client browser interrogation, such as indications of automation and browser setting inconsistencies. This information is retrieved by the scripts that are run by the Challenge action and by the client application SDKs. The scripts actively interrogate the browser and put the results into the token. + Additionally, when you implement a client application integration SDK, the token includes passively collected information about the end user's interactivity with the application page. Interactivity includes mouse movements, key presses, and interactions with any HTML form that's present on the page. This information helps AWS WAF detect the level of human interactivity in the client, to challenge users that do not seem to be human. For information about client side integrations, see [Client application integrations in AWS WAF](waf-application-integration.md). For security reasons, AWS doesn't provide a complete description of the contents of AWS WAF tokens or detailed information about the token encryption process. # Setting timestamp expiration and token immunity times in AWS WAF Setting timestamp expiration and token immunity times This section explains how challenge and CAPTCHA timestamps expire. AWS WAF uses challenge and CAPTCHA immunity times to control how frequently a single client session can be presented with a challenge or CAPTCHA. After an end user successfully responds to a CAPTCHA, the CAPTCHA immunity time determines how long the end user remains immune from being presented with another CAPTCHA. Similarly, the challenge immunity time determines how long a client session remains immune from being challenged again after successfully responding to a challenge. **How AWS WAF token immunity times work** AWS WAF records a successful response to a challenge or CAPTCHA by updating the corresponding timestamp inside the token. When AWS WAF inspects the token for challenge or CAPTCHA, it subtracts the timestamp from the current time. If the result is greater than the configured immunity time, the timestamp is expired. **Configurable aspects of AWS WAF token immunity times** You can configure the challenge and CAPTCHA immunity times in the protection pack (web ACL) and also in any rule that uses the CAPTCHA or Challenge rule action. + The default protection pack (web ACL) setting for both immunity times is 300 seconds. + You can specify the immunity time for any rule that uses the CAPTCHA or Challenge action. If you don't specify the immunity time for the rule, it inherits the setting from the protection pack (web ACL). + For a rule inside a rule group that uses the CAPTCHA or Challenge action, if you don't specify the immunity time for the rule, it will inherit the setting from each protection pack (web ACL) where you use the rule group. + The application integration SDKs use the protection pack (web ACL)'s challenge immunity time. + The minimum value for the challenge immunity time is 300 seconds. The minimum value for the CAPTCHA immunity time is 60 seconds. The maximum value for both immunity times is 259,200 seconds, or three days. You can use the protection pack (web ACL) and rule level immunity time settings to tune the CAPTCHA action, Challenge, or SDK challenge management behavior. For example, you might configure rules that control access to highly sensitive data with low immunity times, and then set higher immunity times in your protection pack (web ACL) for your other rules and the SDKs to inherit. In particular for CAPTCHA, solving a puzzle can degrade your customer's website experience, so tuning the CAPTCHA immunity time can help you mitigate the impact on customer experience while still providing the protections that you want. For additional information about tuning the immunity times for your use of the Challenge and CAPTCHA rule actions, see [Best practices for using the CAPTCHA and Challenge actions](waf-captcha-and-challenge-best-practices.md). # Where to set the AWS WAF token immunity times Where to set the immunity times You can set the immunity times in your protection pack (web ACL) and in your rules that use the Challenge and CAPTCHA rule actions. For general information about managing a protection pack (web ACL) and its rules, see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md). **Where to set the immunity time for a protection pack (web ACL)** + **Console** – When you edit the protection pack (web ACL), in the **Rules** tab, edit and change the settings in the **protection pack (web ACL) CAPTCHA configuration** and **protection pack (web ACL) Challenge configuration** panes. In the console, you can configure the protection pack (web ACL) CAPTCHA and challenge immunity times only after you've created the protection pack (web ACL). + **Outside of the console** – The protection pack (web ACL) data type has CAPTCHA and challenge configuration parameters, which you can configure and provide to your create and update operations on the protection pack (web ACL). **Where to set the immunity time for a rule** + **Console** – When you create or edit a rule and specify the CAPTCHA or Challenge action, you can modify the rule's immunity time setting. + **Outside of the console** – The rule data type has CAPTCHA and challenge configuration parameters, which you can configure when you define the rule. # Specifying token domains and domain lists in AWS WAF Specifying token domains and domain listsAWS WAF allows token sharing across multiple protected applications You can enable the use of tokens across multiple protected applications by configuring a token domain list for your protection pack (web ACL). This section explains how to configure the domains that AWS WAF uses in tokens and that it accepts in tokens. When AWS WAF creates a token for a client, it configures it with a token domain. When AWS WAF inspects a token in a web request, it rejects the token as invalid if its domain doesn't match any of the domains that are considered valid for the protection pack (web ACL). By default, AWS WAF only accepts tokens whose domain setting exactly matches the host domain of the resource that's associated with the protection pack (web ACL). This is the value of the `Host` header in the web request. In a browser, you can find this domain in the JavaScript `window.location.hostname` property and in the address that your user sees in their address bar. You can also specify acceptable token domains in your protection pack (web ACL) configuration, as described in the following section. In this case, AWS WAF accepts both exact matches with the host header and matches with domains in the token domain list. You can specify token domains for AWS WAF to use when setting the domain and when evaluating a token in a protection pack (web ACL). The domains that you specify can't be public suffixes such as `gov.au`. For the domains that you can't use, see the list [https://publicsuffix.org/list/public_suffix_list.dat](https://publicsuffix.org/list/public_suffix_list.dat) under [Public suffix list](https://publicsuffix.org/list/). ## AWS WAF protection pack (web ACL) token domain list configuration AWS WAF protection pack (web ACL) token domain list You can configure a protection pack (web ACL) to share tokens across multiple protected resources by providing a token domain list with the additional domains that you want AWS WAF to accept. With a token domain list, AWS WAF still accepts the resource's host domain. Additionally, it accepts all domains in the token domain list, including their prefixed subdomains. For example, a domain specification `example.com` in your token domain list matches `example.com` (from `http://example.com/`), `api.example.com`, (from `http://api.example.com/`), and `www.example.com` (from `http://www.example.com/`). It doesn't match `example.api.com`, (from `http://example.api.com/`), or `apiexample.com` (from `http://apiexample.com/`). You can configure the token domain list in your protection pack (web ACL) when you create or edit it. For general information about managing a protection pack (web ACL), see [Viewing web traffic metrics in AWS WAF](web-acl-working-with.md). ## AWS WAF token domain settings Token domain settings AWS WAF creates tokens at the request of the challenge scripts, which are run by the application integration SDKs and the Challenge and CAPTCHA rule actions. The domain that AWS WAF sets in a token is determined by the type of challenge script that's requesting it and any additional token domain configuration that you provide. AWS WAF sets the domain in the token to the shortest, most general setting that it can find in the configuration. + **JavaScript SDK** – You can configure the JavaScript SDK with a token domain specification, which can include one or more domains. The domains that you configure must be domains that AWS WAF will accept, based on the protected host domain and the protection pack (web ACL)'s token domain list. When AWS WAF issues a token for the client, it sets the token domain to one that matches the host domain and is the shortest, from among the host domain and the domains in your configured list. For example, if the host domain is `api.example.com` and the token domain list has `example.com`, AWS WAF uses `example.com` in the token, because it matches the host domain and is shorter. If you don't provide a token domain list in the JavaScript API configuration, AWS WAF sets the domain to the host domain of the protected resource. For more information, see [Providing domains for use in the tokens](waf-js-challenge-api-set-token-domain.md). + **Mobile SDK** – In your application code, you must configure the mobile SDK with a token domain property. This property must be a domain that AWS WAF will accept, based on the protected host domain and the protection pack (web ACL)'s token domain list. When AWS WAF issues a token for the client, it uses this property as the token domain. AWS WAF doesn't use the host domain in the tokens that it issues for the mobile SDK client. For more information, see the `WAFConfiguration` `domainName` setting at [AWS WAF mobile SDK specification](waf-mobile-sdk-specification.md). + **Challenge action** – If you specify a token domain list in the protection pack (web ACL), AWS WAF sets the token domain to one that matches the host domain and is the shortest, from among the host domain and the domains in the list. For example, if the host domain is `api.example.com` and the token domain list has `example.com`, AWS WAF uses `example.com` in the token, because it matches the host domain and is shorter. If you don't provide a token domain list in the protection pack (web ACL), AWS WAF sets the domain to the host domain of the protected resource. # Types of token labels in AWS WAF Types of token labelsAWS WAF challenge and CAPTCHA token labeling Token management now adds labels for the CAPTCHA token and has enhanced the token labeling for the challenge token. AWS WAF token labeling adds browser fingerprint Token management now adds a label for the browser fingerprint. This section describes the labels that AWS WAF token management adds to web requests. For general information about labels, see [Web request labeling in AWS WAF](waf-labels.md). When you use any of the AWS WAF bot or fraud control managed rule groups, the rule groups use AWS WAF token management to inspect the web request tokens and apply token labeling to the requests. For information about the managed rule groups, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md), [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md), and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md) . **Note** AWS WAF applies token labels only when you use one of these intelligent threat mitigation managed rule groups. Token management can add the following labels to web requests. **Client session label** The label `awswaf:managed:token:id:identifier` contains a unique identifier that AWS WAF token management uses to identify the client session. The identifier can change if the client acquires a new token, for example after discarding the token it was using. **Note** AWS WAF doesn't report Amazon CloudWatch metrics for this label. **Browser fingerprint label** The label `awswaf:managed:token:fingerprint:fingerprint-identifier` contains a robust browser fingerprint identifier that AWS WAF token management computes from various client browser signals. This identifier stays the same across multiple token acquisition attempts. The fingerprint identifier is not unique to a single client. **Note** AWS WAF doesn't report Amazon CloudWatch metrics for this label. **Token status labels: Label namespace prefixes** Token status labels report on the status of the token and of the challenge and CAPTCHA information that it contains. Each token status label begins with one of the following namespace prefixes: + `awswaf:managed:token:` – Used to report the general status of the token and to report on the status of the token's challenge information. + `awswaf:managed:captcha:` – Used to report on the status of the token's CAPTCHA information. **Token status labels: Label names** Following the prefix, the rest of the label provides detailed token status information: + `accepted` – The request token is present and contains the following: + A valid challenge or CAPTCHA solution. + An unexpired challenge or CAPTCHA timestamp. + A domain specification that's valid for the protection pack (web ACL). Example: The label `awswaf:managed:token:accepted` indicates that the web requests's token has a valid challenge solution, an unexpired challenge timestamp, and a valid domain. + `rejected` – The request token is present but doesn't meet the acceptance criteria. Along with the rejected label, token management adds a custom label namespace and name to indicate the reason. + `rejected:not_solved` – The token is missing the challenge or CAPTCHA solution. + `rejected:expired` – The token's challenge or CAPTCHA timestamp has expired, according to your protection pack (web ACL)'s configured token immunity times. + `rejected:domain_mismatch` – The token's domain isn't a match for your protection pack (web ACL)'s token domain configuration. + `rejected:invalid` – AWS WAF couldn't read the indicated token. Example: The labels `awswaf:managed:captcha:rejected` and `awswaf:managed:captcha:rejected:expired` together indicate that the request didn't have a valid CAPTCHA solve because the CAPTCHA timestamp in the token has exceeded the CAPTCHA token immunity time that's configured in the protection pack (web ACL). + `absent` – The request doesn't have the token or the token manager couldn't read it. Example: The label `awswaf:managed:captcha:absent` indicates that the request doesn't have the token. # Blocking requests that don't have a valid AWS WAF token Blocking requests that don't have a valid token This section explains how to block login requests that are missing their tokens when using the AWS WAF mobile SDK. When you use the intelligent threat AWS Managed Rules rule groups `AWSManagedRulesACFPRuleSet`, `AWSManagedRulesATPRuleSet`, and `AWSManagedRulesBotControlRuleSet`, the rule groups invoke AWS WAF token management to evaluate the status of the web request token and to label the requests accordingly. **Note** Token labeling is only applied to web requests that you evaluate using one of these managed rule groups. For information about the labeling that token management applies, see the preceding section, [Types of token labels in AWS WAF](waf-tokens-labeling.md). The intelligent threat mitigation managed rule groups then handle token requirements as follows: + The `AWSManagedRulesACFPRuleSet` `AllRequests` rule is configured to run the Challenge action against all requests, effectively blocking any that don't have the `accepted` token label. + The `AWSManagedRulesATPRuleSet` blocks requests that have the `rejected` token label, but it doesn't block requests with the `absent` token label. + The `AWSManagedRulesBotControlRuleSet` targeted protection level challenges clients after they send five requests without an `accepted` token label. It doesn't block an individual request that doesn't have a valid token. The common protection level of the rule group doesn't manage token requirements. For additional details about the intelligent threat rule groups, see [AWS WAF Fraud Control account creation fraud prevention (ACFP) rule group](aws-managed-rule-groups-acfp.md), [AWS WAF Fraud Control account takeover prevention (ATP) rule group](aws-managed-rule-groups-atp.md) and [AWS WAF Bot Control rule group](aws-managed-rule-groups-bot.md). **To block requests that are missing tokens when using the Bot Control or ATP managed rule group** With the Bot Control and ATP rule groups, it's possible for a request without a valid token to exit the rule group evaluation and continue to be evaluated by the protection pack (web ACL). To block all requests that are missing their token or whose token is rejected, add a rule to run immediately after the managed rule group to capture and block requests that the rule group doesn't handle for you. The following is an example JSON listing for a protection pack (web ACL) that uses the ATP managed rule group. The protection pack (web ACL) has an added rule to capture the `awswaf:managed:token:absent` label and handle it. The rule narrows its evaluation to web requests going to the login endpoint, to match the scope of the ATP rule group. The added rule is listed in bold. ``` { "Name": "exampleWebACL", "Id": "55555555-6666-7777-8888-999999999999", "ARN": "arn:aws:wafv2:us-east-1:111111111111:regional/webacl/exampleWebACL/55555555-4444-3333-2222-111111111111", "DefaultAction": { "Allow": {} }, "Description": "", "Rules": [ { "Name": "AWS-AWSManagedRulesATPRuleSet", "Priority": 1, "Statement": { "ManagedRuleGroupStatement": { "VendorName": "AWS", "Name": "AWSManagedRulesATPRuleSet", "ManagedRuleGroupConfigs": [ { "AWSManagedRulesATPRuleSet": { "LoginPath": "/web/login", "RequestInspection": { "PayloadType": "JSON", "UsernameField": { "Identifier": "/form/username" }, "PasswordField": { "Identifier": "/form/password" } }, "ResponseInspection": { "StatusCode": { "SuccessCodes": [ 200 ], "FailureCodes": [ 401, 403, 500 ] } } } } ] } }, "OverrideAction": { "None": {} }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "AWS-AWSManagedRulesATPRuleSet" } }, { "Name": "RequireTokenForLogins", "Priority": 2, "Statement": { "AndStatement": { "Statements": [ { "Statement": { "LabelMatchStatement": { "Scope": "LABEL", "Key": "awswaf:managed:token:absent" } } }, { "ByteMatchStatement": { "SearchString": "/web/login", "FieldToMatch": { "UriPath": {} }, "TextTransformations": [ { "Priority": 0, "Type": "NONE" } ], "PositionalConstraint": "STARTS_WITH" } }, { "ByteMatchStatement": { "SearchString": "POST", "FieldToMatch": { "Method": {} }, "TextTransformations": [ { "Priority": 0, "Type": "NONE" } ], "PositionalConstraint": "EXACTLY" } } ] } }, "Action": { "Block": {} }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "RequireTokenForLogins" } } ], "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "exampleWebACL" }, "Capacity": 51, "ManagedByFirewallManager": false, "RetrofittedByFirewallManager": false, "LabelNamespace": "awswaf:111111111111:webacl:exampleWebACL:" } ``` # Required configuration for Application Load Balancers that are CloudFront origins Configuration for Application Load Balancers that are CloudFront origins Read this section if you associate your protection pack (web ACL) to an Application Load Balancer and you deploy the Application Load Balancer as the origin for a CloudFront distribution. With this architecture, you need to provide the following additional configuration in order for the token information to be handled correctly. + Configure CloudFront to forward the `aws-waf-token` cookie to the Application Load Balancer. By default, CloudFront removes cookies from the web request before forwarding it to the origin. To keep the token cookie with the web request, configure CloudFront cache behavior to include either just the token cookie or all cookies. For information about how to do this, see [Caching content based on cookies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html) in the *Amazon CloudFront Developer Guide*. + Configure AWS WAF so that it recognizes the domain of the CloudFront distribution as a valid token domain. By default, CloudFront sets the `Host` header to the Application Load Balancer origin, and AWS WAF uses that as the domain of the protected resource. The client browser, however, sees the CloudFront distribution as the host domain, and tokens that are generated for the client use the CloudFront domain as the token domain. Without any additional configuration, when AWS WAF checks the protected resource domain against the token domain, it will get a mismatch. To fix this, add the CloudFront distribution domain name to the token domain list in your protection pack (web ACL) configuration. For information about how to do this, see [AWS WAF protection pack (web ACL) token domain list configuration](waf-tokens-domains.md#waf-tokens-domain-lists).