Captcha & Form Protection manual.

From installation to fine-tuning: what is protected out of the box, how to choose visible tasks, add forms of other plugins and read the figures on the overview.

System requirements

Shopware 6.6 or 6.7. On installation the plugin creates its own tables for stamps, counting, statistics and the log. Rebuilding the theme is not necessary.

Good to know: Protected forms can only be submitted with JavaScript switched on, because the browser has to solve the task.

Installation

The easiest way is the Plugin Suite: select the plugin, install, done. Alternatively upload the ZIP in the admin under Extensions, My extensions, Upload extension, then install and activate it. SSH access is not needed.

Licence

The plugin needs a licence. When you start the test or rent the plugin in the Plugin Suite, the Plugin Suite enters the key by itself. If you received a key from us, enter it in the licence view of the module.

Important: Without a valid licence the protection does not apply. Forms then pass unchecked, and the module only shows the licence view.

Opening the module

The module is located under Administration, Plugin Suite, Captcha & Form Protection. It has three tabs: Overview, Log and Settings. At the top you choose the sales channel and the appearance (light, dark or like the system).

First steps

After activating there is nothing else to do. By default:

  • The protection is active and works invisibly
  • Registration, login, contact form, newsletter, password request, reviews and revocation are protected
  • Proof of work, time check, hidden field and slowdown are switched on
  • Disposable addresses and domains without a mail server are rejected
  • Below protected forms the line "Protected without cookies and without third parties" is shown
Tip: After installation submit the contact form once yourself. The submission then appears on the overview under "Accepted".

The overview

The overview shows what happened in 7, 30 or 90 days:

  • Key figures: blocked today, blocked in 7 days, blocked and accepted in the period, share blocked and the number of addresses currently slowed
  • Submissions per day: a chart with accepted and blocked submissions. Hover over a day or tap it to see the numbers
  • Forms: which forms are protected and how many submissions per form were accepted or blocked
  • Reasons for blocking: why submissions were rejected, such as "Submitted too fast" or "Disposable address"
  • Disposable addresses: number of domains in the list and its date, with the button "Load list now"
  • Detected forms: submissions to forms that are not yet protected

The log

The log lists every rejected submission with time, form, reason, slowdown level and sales channel. You can filter by form and reason and search for an address or domain.

Stored are the shortened address and, for e-mail checks, only the domain, no full address and no content. "Clear log" deletes all entries, the figures on the overview remain.

Reasons for blocking

These reasons can appear on the overview and in the log:

  • Hidden field filled in
  • Form never opened in a browser
  • Forged stamp
  • Stamp of a different form
  • Task answered incorrectly
  • Task not solved
  • Stamp expired
  • Different network than on opening
  • Submitted too fast
  • Proof of work not solved
  • Stamp used twice
  • Disposable address
  • Domain without mail server
  • Blocked domain

Choosing the type of captcha

Under Settings, Type of captcha you decide whether the protection works invisibly or the visitor solves a visible task. There is a default for all forms and a separate choice per form.

  • Invisible: bothers nobody, set by default
  • Checkbox to click: a tick "I am human"
  • Slider: move the slider to the right
  • Press and hold button: for the configured hold time
  • Maths or text question: a small sum or a question of your own
  • Picture selection: pick the named picture from twelve symbols

The invisible checks always run as well. Question and image choice require a correct answer, there is one attempt per stamp.

Tip: There is little room in the footer. For the newsletter, Invisible or the checkbox fit best.

Own questions

In the field "Own questions" you enter one question per line. Separate question and answer with a vertical bar, several correct answers with a semicolon. Case does not matter.

Example: What colour is the sky in good weather|blue;light blue

Without own questions the plugin asks small sums.

Task on suspicion

When the slowdown applies to an address, this address gets a visible task instead of the invisible check. By default this is the slider. Forms for which you chose a visible task yourself keep theirs.

Protecting additional forms

You add forms of other plugins by their path. Under Settings, Protected forms, Additional forms enter one path per line, for example /my-plugin/request. An asterisk at the end protects all paths that start like this.

Detection makes it easier: when "Detect new forms" is switched on, the plugin remembers submissions to unprotected forms and lists them on the overview under "Detected forms". "Protect" takes over the path, "Hide" removes the row. Only path, route and count are stored.

Good to know: Routes of Shopware itself such as cart, order and customer account are not recorded.

The slowdown

The slowdown counts submissions per address within a window of ten minutes. An accepted submission counts one point, a rejected one three.

  • First level: from the configured value (8 points by default), waiting time 5 seconds
  • Second level: from double, waiting time 15 seconds
  • Third level: from four times, the longest waiting time (30 seconds by default)

With every level the computing task gets harder. During the waiting time the visitor sees a notice, afterwards the form is submitted by itself. Nobody is banned.

E-mail address check

For registration, newsletter and contact form the plugin checks the address:

  • Disposable addresses: addresses of disposable mailbox services are rejected. The list ships with the plugin and is renewed once a week if that is switched on
  • Domains without a mail server: DNS is used to check whether the domain can receive e-mails. This catches typos and invented addresses
  • Own lists: domains you want to block additionally or allow explicitly
Good to know: If the server's name resolution is disturbed, nobody is rejected. When the list is reloaded, no data of the shop or its customers is transferred.

Sales channels and inheritance

At the top of the module you choose "All sales channels" or a single sales channel. Fields without their own value take the setting from "All sales channels". Click "Inherited" or "Own value" to switch between the two.

Changing texts

All texts the visitor sees are snippets and can be changed under Settings, Snippets. The most important ones:

  • stawFormGuard.badge: Notice line below protected forms ("Protected without cookies and without third parties")
  • stawFormGuard.checkbox: Text at the checkbox ("I am human")
  • stawFormGuard.slider: Text at the slider ("Slide to the right")
  • stawFormGuard.hold: Text at the hold button ("Press and hold")
  • stawFormGuard.alternative: Link to the fallback question ("Answer a question instead")
  • stawFormGuard.wait: Notice during the waiting time ("Many attempts from your connection. The form will be sent in a few seconds")
  • error.STAW_FORM_GUARD_FAILED: Message when the check failed ("The security check failed. Please reload the page and submit the form again.")
  • error.STAW_FORM_GUARD_EMAIL: Message for a rejected address ("This e-mail address is not accepted. Please use a different address.")

Behind a proxy or CDN

If the shop is behind a proxy or CDN, it initially only sees that address. The overview then shows a notice. Enter the proxy in the file .env under TRUSTED_PROXIES so that slowdown and counting use the real address of the visitors.

Limits of the protection

A captcha stops the bulk of bots. It does not reliably stop targeted attackers using real browsers or bought computing time. In such cases the slowdown, the e-mail address check and a look into the log help in addition.

Troubleshooting

A real customer is rejected: Look up the reason in the log. For "Submitted too fast" a shorter minimum time helps, for "Different network than on opening" switching off the binding to the network.
An integration can no longer submit a form: Enter its address under General, Addresses without check.
The slowdown hits all visitors at once: The shop is probably behind a proxy and only sees its address. See "Behind a proxy or CDN".
The notice line should go: Switch off "Show notice line in the form" under General.

Support

Questions and requests are welcome directly to us - support comes from the developer, not from a queue. You can also request a feature through the Plugin Suite in the admin.

All settings

Every setting of the plugin with its default value and explanation, in the same order as in the administration. The texts come straight from the plugin (version 1.1.1).

General

Switch protection on and off, notice line in the form and exceptions.

Protection activeDefault: on

Switches the whole protection on or off. When off, no forms are checked and no script is loaded.

Show notice line in the formDefault: on

Shows the line Protected without cookies and without third parties below protected forms. The text can be changed under Settings, Snippets (stawFormGuard.badge).

Do not check logged-in customersDefault: off

Submissions by logged-in customers pass without a check. Guests do not count as logged in. Only switch on if the registration itself is protected.

Addresses without checkDefault: empty

One address or network per line, for example 203.0.113.7 or 203.0.113.0/24. For your own monitoring or integrations that submit forms automatically.

Type of captcha

Whether the protection works invisibly or the visitor solves a visible task. Adjustable as default and per form. The invisible checks always run as well.

Default for all formsDefault: Invisible

Invisible bothers nobody. Checkbox, slider and hold show the protection and stop simple bots. Question and picture selection require a correct answer. Picture selection is the weakest protection and only solvable for screen readers via the fallback question.

Task on suspicionDefault: Slider

When the slowdown applies to an address, it gets this visible task instead of the invisible check. Forms with their own visible task keep theirs.

Type for registrationDefault: Same as default

Own type for the registration. Same as default takes the setting above.

Type for loginDefault: Same as default

Own type for the login. Same as default takes the setting above.

Type for the contact formDefault: Same as default

Own type for the contact form. Same as default takes the setting above.

Type for the newsletterDefault: Same as default

Own type for the newsletter. Space in the footer is tight, invisible or the checkbox fit best there.

Type for the password requestDefault: Same as default

Own type for the forgot password form. Same as default takes the setting above.

Type for reviewsDefault: Same as default

Own type for submitting reviews. Same as default takes the setting above.

Type for revocationDefault: Same as default

Own type for the revocation form. Same as default takes the setting above.

Type for additional formsDefault: Same as default

Own type for the paths entered under Additional forms.

Hold time in secondsDefault: 2

How long the button must be held in press and hold mode.

Own questionsDefault: empty

One question per line, question and answer separated by a vertical bar, several correct answers by semicolon. Example: What colour is the sky in good weather, then the bar, then blue. Case does not matter. Without own questions the plugin asks a maths question in words. Own questions apply in all languages.

Colour of the taskDefault: empty

Colour for check mark, slider and selection as a hex value, for example #0b5c7d. Empty takes the primary colour of the theme. Font, borders and radius always come from the theme.

Protected forms

Which storefront forms are checked. Each form can be switched individually.

RegistrationDefault: on

Creating a customer account, also in the checkout and as a guest.

LoginDefault: on

Customer login in the storefront. Slows down password guessing.

Contact formDefault: on

The Shopware contact form, also in shopping experiences.

NewsletterDefault: on

Newsletter subscription and unsubscription, also in the footer and in shopping experiences.

Password requestDefault: on

The forgot password form. Prevents waves of password e-mails.

ReviewsDefault: on

Submitting product reviews.

RevocationDefault: on

The revocation form of newer Shopware versions. No effect in older versions.

Additional formsDefault: empty

Paths of further forms, one per line, for example /my-plugin/request. A trailing asterisk protects all paths starting like this. Suitable for forms from other plugins that submit via POST.

Detect new formsDefault: on

Remembers submissions to forms that are not protected and lists them on the overview under Detected forms. Only path, route and count are stored.

Checks

The invisible checks of the first stage: proof of work, time, hidden field and signed stamp.

Background proof of workDefault: on

The browser solves a computing task unnoticed before submitting. Barely measurable for visitors, expensive for mass submissions.

Difficulty of the taskDefault: Normal (recommended)

Determines how long the browser computes. The slowdown raises the difficulty further on many attempts.

Time checkDefault: on

A form submitted faster than a human can fill it in is rejected. Real visitors do not notice, their browser waits by itself.

Minimum time in secondsDefault: 2

Time between the first click into the form and submitting. 2 to 4 seconds are recommended.

Hidden fieldDefault: on

Adds a field that is invisible to humans. Bots that fill in every field give themselves away.

Bind stamp to the visitor networkDefault: off

The stamp is only valid for the network the form was opened from. Stricter, but may reject visitors whose provider changes the address widely while filling in. Off by default.

Stamp validity in minutesDefault: 60

How long a form may stay open after the first click. After that the browser fetches a new stamp by itself on submit.

Slowdown on many attempts

Addresses with many submissions in a short time have to wait and get a harder task. Nobody is locked out.

Slowdown activeDefault: on

Slows addresses with many submissions within ten minutes in three levels: 5 seconds, 15 seconds and the longest waiting time, each with a harder task.

Slowdown from pointsDefault: 8

An accepted submission counts one point, a rejected one three. From this value within ten minutes the first level applies, from double the second, from four times the third.

Longest waiting time in secondsDefault: 30

Waiting time of the third level. The visitor sees a notice meanwhile, the form is then submitted by itself.

E-mail address check

Rejects disposable addresses and domains without a mail server on registration, newsletter and contact form.

Reject disposable addressesDefault: on

Rejects addresses of disposable mailbox services. The visitor is asked to use a different address.

Reject domains without mail serverDefault: on

Checks via DNS whether the domain can receive e-mails. Catches typos and invented addresses. If the server's name resolution is disturbed, nobody is rejected.

Own blocked domainsDefault: empty

One domain per line. Subdomains are included.

Always allowed domainsDefault: empty

One domain per line. These domains are never rejected, even if they are on the disposable list.

Refresh list weeklyDefault: on

Downloads the list of disposable domains from GitHub once a week. No shop or customer data is transmitted.

Log

Whether rejected submissions are logged and for how long.

Log rejected submissionsDefault: on

Writes every rejection with its reason to the log. The figures on the overview are kept independently.

Retention in daysDefault: 30

Older entries are deleted automatically by the daily task.

Availability

Directly from Stone & Water

Through the Plugin Suite

Monthly4,99 €
Best valueYearly50,90 €15 % cheaper

All prices net, plus VAT.

Download the free Plugin Suite and upload it in the admin, no SSH needed. It installs and updates the plugin with one click. You buy the licence directly from us, with an invoice from us and support straight from the developer.

Download Plugin Suite+49 2555 9997342

Testing

30 days free

In the Plugin Suite you start the test with one click. After 30 days it turns into a rental unless you end it beforehand. You can end it at any time in the Plugin Suite.