As you might imagine, the internals of how Gatekeeper computes resolves various visitor groups, page groups, and policies are quite complex. For the nerds among us, here is an inside look into Gatekeeper's rules engine.

The final decision for a set of inputs and a set configuration is known as a visit authorization (whether the authorization is allow, deny, CAPTCHA, or some custom authorization). Determining a visit authorization will start with your highest priority policy (the policy with the largest priority number) and evaluate it and each subsequent policy until one policy is found to apply. For each policy in the chain, the following steps are taken:

Visitor check

A policy's visitor groups are checked for a trigger. A visitor group is triggered when at least one of its visitors matches the visit.

For example, if visitor group blacklisted IP addresses contains visitor 1.2.3.4, and the visit IP address is 1.2.3.4, blacklisted IP addresses would be triggered.

If no trigger is found, the policy is skipped. If applicable, user agent is also checked to determine if the visit matches any tags, such as self-identified bot or Google crawler.

Action check

If a policy's visitor group matches, then that policy's page groups are checked. A page group is triggered when the visit URL matches at least one page group.

For example, if page group internal content contains page /i/.+, and the visit URL is https://example.com/i/console, internal content would be triggered.

Note: this check is not performed for policies that apply to CAPTCHA attempts.

If no page group trigger is found, the policy is skipped.

Frequency check

Policies based on page groups

If a policy involves visiting content, Gatekeeper will look at the number of visits that match the corresponding page group(s). For example, if a policy is set to trigger after 30 visits in 5 days and has one page group, internal content, the number of visits to pages that match internal content within the past 5 days is used to determine whether the policy triggers.

If the number of visits does not meet the policy's threshold, the policy is skipped. Only visits within the policy time interval are counted.

CAPTCHA-based policies

If the policy involves CAPTCHA challenges, Gatekeeper will use the results of CAPTCHA challenges within the policy time interval (whether the CAPTCHA challenge was solved, failed, or ignored).

For example, if the policy is set to trigger after 10 FAILED CAPTCHAs in 5 days, the number of CAPTCHA attempts with status FAILED within that past 5 days is queried.

Note: FAILED and UNSOLVED attempts are counted starting from the last SOLVED CAPTCHA. This allows users to effectively "reset" their count by proving that they are human at least once.

If the number of CAPTCHA challenges does not meet the policy's threshold, the policy is skipped.

If the policy has the CAPTCHA authorization, a couple more checks are made.

First, the number of UNSOLVED/FAILED CAPTCHA attempts is queried. If there is at least one outstanding UNSOLVED or FAILED attempt, the policy is immediately triggered. This is to prevent a user from simply ignoring CAPTCHAs and reloading the page.

Second, the number of visits is compared against the policy grace interval. After the first trigger, policies that require CAPTCHA authorization will wait a certain number of visits before allowing themselves to be retriggered (the "grace interval").

For example, a policy may trigger after 30 visits in 5 days, and then every 100 visits. This policy will trigger on the 30th visit, and again on the 130th visit.

If the number of visits is within the policy grace interval, the policy is skipped.

For an overview of how Gatekeeper handles CAPTCHA responses, visit our page on how CAPTCHA authorizations work.