CAPTCHA Providers

What Are CAPTCHA Providers?

CAPTCHA Providers are the profiles in which the CAPTCHA service to be used to verify that the user is a human in the AGS access flow is defined. TR7 supports TR7 Captcha (a text or a math question), which runs on the device and requires no external connection, and three external services: Google reCAPTCHA (v2 Checkbox, v2 Invisible, v3), hCaptcha and Cloudflare Turnstile. The site and secret keys and the route table from which the verification requests go out for the external services, and the question type, the difficulty, the attempt limit and the timeout for TR7 Captcha are kept in this profile. With Do Not Ask Again Timeout it is determined for how long a successfully solved CAPTCHA is considered valid.

The provider is selected for the CAPTCHA level on the Account Lockout Policies screen and for the Captcha action on the Bot Protection Policies screen. Two built-in profiles come with TR7 (Standard TR7 CAPTCHA, Hard TR7 CAPTCHA); the built-in lockout and bot profiles that use a CAPTCHA use Standard TR7 CAPTCHA. The built-in profiles do not appear in the list of this screen, they are selected directly in the selectors in the policy forms.

4

Provider

TR7 Captcha · Google reCAPTCHA · hCaptcha · Cloudflare Turnstile

Offline

TR7 Captcha

A text or a math question, 1–5 difficulty, produced on the device; no external connection is required

v2 · v3

Google reCAPTCHA

v2 Checkbox, v2 Invisible or the v3 score threshold (the default 0.5)

Route Table

External Verification

The verification requests of the external providers go out from the selected route table

2

Built-in Profiles

Standard TR7 CAPTCHA · Hard TR7 CAPTCHA (they do not appear in the list)

Counters

Live Statistics

The shown, correct and wrong solution counters on a provider basis

How does it work?

1. The provider is defined on this screen: the Provider is selected; the site and secret keys and the Route Table are configured in the external services, and the question type and the difficulty in TR7 Captcha.
2. The provider is selected in the Captcha Provider field of a lockout policy or in a bot policy with the Captcha action; the policy is bound to the vService.
3. When the policy reaches the CAPTCHA level, the verification of the provider is shown on the access page; in the external providers the response is verified from the service of the provider over the Route Table, and in TR7 Captcha the question is produced and checked on the device.
4. A successful solution is considered valid for the Do Not Ask Again Timeout duration; when the duration expires or if Always Ask is selected, it is asked again on every trigger.

Built-in Profiles

Profile	Provider	Captcha Type	Difficulty Level	CAPTCHA Max. Attempts	CAPTCHA Timeout	Do Not Ask Again Timeout
Standard TR7 CAPTCHA (the provider of the built-in policies)	TR7 Captcha	Text	3	5	5 minutes	5 minutes
Hard TR7 CAPTCHA	TR7 Captcha	Text	5	5	3 minutes	3 minutes

Since the built-in profiles are not in the list, they are not edited or deleted from this screen.

Operational Best Practices

• TR7 Captcha if there is no external connection. The external providers require the browser of the user and TR7 to access the service of the provider; TR7 Captcha must be used on closed networks.
• The Route Table must be selected correctly. The verification requests of the external provider go out from the Route Table in the profile; a route table that has internet access must be selected.
• The keys from the provider console. The site and secret keys must be created for the domain name of the vService in the management console of the provider; the secret key is masked in the preview and the saved value comes filled in the edit form.
• The reCAPTCHA v3 threshold. The v3 score is between 0 (a bot) and 1 (a human); as v3 Score Threshold is raised, more legitimate users are rejected. 0.5 is the starting value.
• The re-asking duration. Do Not Ask Again Timeout determines for how long the solved CAPTCHA stays valid without disturbing the user again; it is kept short (a few minutes) in the lockout scenarios and longer in the bot protection scenarios.
• The policies before deleting. The delete confirmation does not show the usage locations; the policies that use the provider must be checked on the Used in tab in the preview.

How to Add?

A new CAPTCHA Providers profile is added through the TR7 web management interface with the following steps:

1. The Configuration Menu is opened by clicking the TR7 logo at the bottom left.
2. The AGS → Protection Policies → CAPTCHA Providers → Add steps are followed.
3. A unique and descriptive name is entered for the profile.
4. The Provider is selected and the fields specific to the provider are filled in.
5. The profile is added by clicking the Add button.

TIP

Reaching the page via quick search

Instead of navigating the menu step by step, the related page is reached directly by using the search bar in the bottom left corner of the screen. The search bar opens with the Alt + T shortcut on Windows and Opt + T on macOS; typing the name of the feature being searched for is then sufficient.

The created profile is used in the Captcha Provider field of the lockout and bot policies. The profile is also defined without leaving the page with the add icon next to this field in the lockout policy form; the created profile comes selected in the field.

CAPTCHA Providers Listing Screen

The list of all CAPTCHA Providers profiles that are added on the TR7 device is reached by following the AGS → Protection Policies → CAPTCHA Providers path. Profile adding, editing and deleting operations are performed on this screen. The built-in profiles are not listed.

CAPTCHA Providers Profiles Listing Form

The table opens with the following columns by default:

Column	Description
Name	The name of the profile.
Provider	The provider: TR7 Captcha, Google reCAPTCHA, hCaptcha or Cloudflare Turnstile.
Do Not Ask Again Timeout	The duration for which the solved CAPTCHA stays valid (e.g. 5 minute(s), 30 second(s)). In the profiles for which no duration is defined, - is displayed in the column; the Always Ask value in the preview is not reflected to the column.

There is no column that is hidden by default. The table is not sorted when it opens; when a column header is clicked, first a descending and then an ascending sort is applied, and on the third click the sort is removed.

The items in the toolbar are arranged from left to right in the following order; the last two items (Page Information and Page Size) are located in the information strip below the table.

Columns

Which columns are shown in the table is selected; all three of the columns come on. In the same panel the columns are reordered by dragging and the alignment is selected per column; the row height is fitted to the page with the Fit rows to the page button and the column layout is returned to the default with the Reset button. When the width badge next to a manually widened column is clicked, the column returns to the automatic width.

Filter

The Filter button is used to filter the profiles shown in the list according to certain criteria. There are two cards in the filter strip; the number next to the card name shows how many different values are found for that card in the profiles in the list:

Card	What it filters
Provider	By the provider (TR7 Captcha / Google reCAPTCHA / hCaptcha / Cloudflare Turnstile).
Used in	The policies that use the profiles and the Unused Entries value, which lists the profiles that are not used anywhere.

Export

The table is exported as Excel, CSV or PDF by clicking the Export button. In the window that opens, the Filename, Format and Data Source, together with the Columns to be exported, are determined; the remaining fields are displayed according to the format: CSV Separator for CSV, Excel Sheet Name for Excel, and Page Orientation and Page Size for PDF.

Add

By clicking the Add button, the form for creating a new profile opens in the Add tab.

Edit

By clicking the Edit button, the edit form of the selected profile opens in the Edit tab. The button becomes enabled only when a single profile is selected.

The edit form is the same as the add form; all the fields including Provider are changed, the secret key fields come filled with the saved value and the button at the bottom of the form carries the name Edit. The change is saved without asking for confirmation.

Delete

When one or more profiles are selected and the Delete button is clicked, the related profiles are deleted. Before deleting, the "Are you sure?" confirmation is asked for.

WARNING

A profile that is in use can also be deleted and the confirmation window does not show the usage locations.

The Captcha Provider reference in the lockout and bot policies that use the profile is not cleared automatically; a provider that cannot be found in the lockout chain is skipped. When the policy form is opened, a new provider must be selected before saving; otherwise the record is not completed and the Invalid option warning is given. The delete operation is written to the user operation record.

Search

Used to search all information in the table.

RegExp Search

Used to search all the information in the table with a regular expression (RegExp). While the usage filter is active, this button is hidden.

Column Based Search

Used to perform a column-based search on the information in the table.

Usage Filter

Used to filter in which policies the profiles are used. While the filter is active, a selector takes the place of the search box; when the icon is clicked again, the search box returns.

Page Information

Contains information about the total number of defined profiles and the number of profiles displayed in the list: Showing N-M of T records and the number of selected profiles (N selected, or Nothing selected when there is no selection).

Page Size

The maximum number of profiles to be displayed on the page is selected. On this screen the default is 100; the options are 5, 10, 20, 50, 100, 200, 500 and All.

Right-Click Menu

When a row is right-clicked, a menu with the profile's name in its title opens. Both operations in the menu apply only to the right-clicked profile; a selection made in the list does not affect the menu.

Operation	What it does
Edit	Opens the editing form of the profile in the Edit tab; it is the same as the form opened by the Edit button in the toolbar.
Delete	Deletes the right-clicked profile; the same confirmation question as the deletion in the toolbar is displayed.

Preview of the Selected Profile

When a row in the list is clicked, the preview of the profile opens on the right of the screen; when the selected row is clicked again, the panel closes. The header contains the puzzle icon, the name of the profile and the Captcha Provider subtitle, and the single operation is at the top right.

Preview of the Selected Profile

Operation	What it does
Edit	Opens the editing form of the profile in the Edit tab.

There are three tabs in the panel; Used in is displayed only if the profile is used in at least one policy:

Details

Lists the settings of the profile row by row (the table below).

Log

Lists the user operations on the profile (adding, editing, deleting) as a timeline.

Used in

Lists the lockout and bot policies that use the profile. The badge next to the tab name shows the usage count.

On the Details tab only the rows belonging to the selected provider are displayed:

Row	Description	Visibility condition
Name	The name of the profile.	Always
Provider	The name of the provider.	Always
Route Table	The route table from which the verification requests go out (e.g. VRRP2).	The external providers
Site Key	The site key.	The external providers
Secret Key	The masked secret key (********).	The external providers
reCAPTCHA Version	v2 Checkbox, v2 Invisible or v3.	Google reCAPTCHA
v3 Score Threshold	The v3 score threshold.	Google reCAPTCHA, v3
Difficulty	The hCaptcha difficulty.	hCaptcha
Mode	The Turnstile mode.	Cloudflare Turnstile
Captcha Type	Text or Math; with the case-insensitivity note in the Text type.	TR7 Captcha
Difficulty Level	The difficulty level.	TR7 Captcha
CAPTCHA Max. Attempts	The attempt limit.	TR7 Captcha
CAPTCHA Timeout	The validity duration of the question.	TR7 Captcha
Do Not Ask Again Timeout	The duration (e.g. 5 minute(s)) or Always Ask.	Always

Profile Add Form

A new CAPTCHA Providers profile is added on the TR7 device by following the AGS → Protection Policies → CAPTCHA Providers → Add steps. The form opens with TR7 Captcha selected; when the Provider is changed, the fields specific to the provider change. Below, first the fields that are common to all the providers and then the own fields of each provider are explained.

Common Fields

INFO

Name Required

The name of the profile; it identifies the profile in the selection in the policy forms, in the live statistics counters and in the logs. The name must be unique on the device; a second profile with the same name is not saved and the Name is used warning is displayed. When it is left empty, the Required field warning is displayed. The name is at most 64 characters.

INFO

Route Table Default: the default route table

The Route Tables record from which the verification requests of the external providers (Google reCAPTCHA, hCaptcha, Cloudflare Turnstile) go out. The field is located under the Name field and is displayed only when an external provider is selected; since TR7 Captcha uses no external connection, it is not displayed in this provider. The field comes filled with the default route table of the device; the name of this table varies by device (e.g. DEFAULT or, as in the screenshot above, DEFAULT_ROUTE).

INFO

Provider Required Default: TR7 Captcha

The CAPTCHA service to be used is selected:

Option	Meaning
TR7 Captcha	A text or a math question produced on the device; no external connection is required. The details: TR7 Captcha.
Google reCAPTCHA	Google's checkbox, invisible or score-based verification. The details: Google reCAPTCHA.
hCaptcha	The hCaptcha verification whose difficulty level is selected. The details: hCaptcha.
Cloudflare Turnstile	Cloudflare's mostly non-interactive verification. The details: Cloudflare Turnstile.

INFO

Do Not Ask Again Timeout Default: Always ask

It is located in the last box of the form in all the providers. While the switch is in the Always Ask position, the CAPTCHA is asked again on every trigger. When the switch is moved to the Select position, the duration for which the successfully solved CAPTCHA is considered valid is entered; seconds, minutes or hours are selected as the unit and a value between 30 seconds and 24 hours is accepted. A profile that is saved without the switch being touched stays as Always Ask.

TR7 Captcha

TR7 Captcha is the provider that produces and checks the question on the device and requires no internet access. It is used on closed networks and in installations in which a dependency on external services is not wanted. The Route Table field is not present in this provider; CAPTCHA Timeout and Do Not Ask Again Timeout are located under the fields specific to the provider.

The Form While TR7 Captcha Is Selected

INFO

Captcha Type Default: Text

The type of the question to be asked of the user is selected:

Option	Meaning
Text	The character string on the image is requested to be typed.
Math	The result of the simple arithmetic operation on the image is requested to be typed.

While Text is selected, the following information band is displayed under the field: Text captcha verification is case-insensitive: visitors can type the characters in upper or lower case. Easily confused characters (such as I, O, 0 and 1) are also left out of generated challenges. The verification is case-insensitive and the characters that can be confused are not taken into the questions.

INFO

Difficulty Level Default: 3

The difficulty level of the question; an integer between 1 and 5 is entered. As the value increases, the question becomes harder to read.

INFO

CAPTCHA Max. Attempts Default: 5

The number of wrong attempts allowed for the same question; an integer between 1 and 10 is entered. When the limit is exceeded, a new question is produced.

INFO

CAPTCHA Timeout Required Default: 5 minutes

The validity duration of the produced question; a value and a unit (seconds, minutes or hours) are entered. On saving, values between 1 minute and 30 minutes are accepted. A question whose duration has expired is considered invalid and a new question is produced.

Google reCAPTCHA

Google reCAPTCHA is Google's verification service. The browser of the user loads Google's script; TR7 has the response coming from the user verified by Google over the Route Table. The keys are created for the domain name of the vService in the Google reCAPTCHA management console.

The Form While Google reCAPTCHA Is Selected

INFO

Site Key Required

The site key created in the reCAPTCHA console; it is used in the verification component added to the access page. It is at most 128 characters.

INFO

Secret Key Required

The secret key created in the reCAPTCHA console; it is the key TR7 uses while having the response verified by Google. It is shown masked (********) in the preview. It is at most 128 characters.

INFO

reCAPTCHA Version Default: v2 Checkbox

The reCAPTCHA version to be used is selected; the version must be the same as the type selected while the key was being created in the console:

Option	Meaning
v2 Checkbox	The user checks the "I'm not a robot" checkbox; if necessary an image question is shown.
v2 Invisible	There is no visible checkbox; the verification is performed in the background and an image question is shown in a suspicious case.
v3	No question is shown to the user; Google produces a score between 0 and 1 and the score is compared with the v3 Score Threshold.

v3 Score Threshold Default: 0.5

Displayed only when v3 is selected as the reCAPTCHA Version. A threshold between 0 and 1 with a step of 0.1 is entered; the scores below this value are expected to be rejected. As the threshold is raised, the verification becomes stricter.

hCaptcha

hCaptcha is a privacy-oriented external verification service. The browser of the user loads the hCaptcha component; TR7 has the response verified by hCaptcha over the Route Table. The keys are created in the hCaptcha management console.

The Form While hCaptcha Is Selected

INFO

Site Key

The site key created in the hCaptcha console. There is no required mark in the form; when the field is left empty, the profile is not saved. It is at most 128 characters.

INFO

Secret Key

The secret key created in the hCaptcha console; it is shown masked (********) in the preview. There is no required mark in the form; when the field is left empty, the profile is not saved. It is at most 128 characters.

INFO

Difficulty Default: Moderate

The difficulty of the question shown to the user is selected:

Option	Meaning
Easy	Easy questions; the user experience is the priority.
Moderate	A balanced difficulty.
Difficult	Hard questions; the bot resistance is the priority.
Always On	The question is shown on every verification.

Cloudflare Turnstile

Cloudflare Turnstile is Cloudflare's verification service, which mostly requires no interaction from the user. The browser of the user loads the Turnstile component; TR7 has the response verified by Cloudflare over the Route Table. The keys are created in the Turnstile section of the Cloudflare panel.

The Form While Cloudflare Turnstile Is Selected

INFO

Site Key Required

The site key of the Turnstile component. It is at most 128 characters.

INFO

Secret Key Required

The secret key of the Turnstile component; it is shown masked (********) in the preview. It is at most 128 characters.

INFO

Mode Default: Managed

How the component appears to the user is selected; the mode must be the same as the mode selected while the component was being created in the Cloudflare panel:

Option	Meaning
Managed	Cloudflare requests a checkbox interaction from the user when necessary.
Non-Interactive	The component is visible, but it requests no interaction from the user.
Invisible	The component is invisible; the verification is performed entirely in the background.

INFO

Add

The profile is added by clicking the Add button; the tab closes and the profile is displayed in the list.

Operating Mechanism

INFO

• Distribution. The profiles are written, together with the AGS database, into the configuration of every vService with an AGS license and are transferred to the AGS access engine; which profile is used is determined by the lockout and bot policies. The verification page and the response check are on the engine side.
• The route table. The Route Table value of the external providers is added to the list of the outgoing route tables of the access engine of the vService; the verification requests go out from this table.
• The bot action. When a bot policy with the Captcha action is triggered, the provider is carried to the access engine with a custom HTTP header added to the request and the verification page is shown.
• The statistics. For every provider used in a lockout policy (while the CAPTCHA level is on and its threshold is defined) or in a bot policy with the Captcha action, the shown, correct and wrong solution counters are monitored with the provider name in the vService live statistics.
• The secret keys. The secret keys are masked in the preview; the saved value comes filled in the edit form.
• Cluster. The profiles are synchronized between the devices with the LB configuration.
• Logs. Adding, editing and deleting are monitored on the User Logs screen as the captcha provider object.

Scope and Limits

INFO

• License. The screen depends on the AGS license; for the details the Products & Licensing page must be consulted.
• Permission. The AGS screens depend on the Load Balancer permission area; for a user who does not have the permission the You don't have access to this page card is displayed instead of the page.
• The name is unique. A second profile carrying the same name is not saved. The check is performed only among the profiles listed on this screen; the names of the built-in profiles do not enter the check.
• The built-in profiles are not listed, they are not edited or deleted from this screen.
• The external providers require internet access (the browser of the user and the selected route table of TR7).
• CAPTCHA Timeout is limited to between 1 and 30 minutes on saving.
• The record limit of the Do Not Ask Again Timeout is wider than the form. While the form accepts at least 30 seconds, the record accepts durations starting from 1 second as well; on a record made without the field being sent at all, 5 minutes is applied.
• Deleting does not perform a reference check; a profile in use is deleted as well.

Usage Locations

Usage location	Field	Purpose
Account Lockout Policies	Captcha Provider (while Enable Captcha Protection is on)	The verification added to the login form before the lockout level
Bot Protection Policies	Captcha Provider (the Captcha action)	The verification to which the triggered request is directed
A vService with AGS enabled → Live Stats	The provider counters	The shown, correct and wrong solution statistics