Google reCaptcha v1.1
This package provides capabilities that extend the Avoka Transact platform for customers wishing to protect their applications from spam and abuse in their forms using the Google reCaptcha services. Google reCaptcha is a free service that uses advanced risk analysis techniques to tell humans and bots apart.
The package supports 2 different experiences to perform the reCaptcha validation.
- Visible reCaptcha v2 - Upon choosing this option, the applicant will be aware of the validation and will trigger it by clicking the "I'm not a robot" check box.
- Invisible reCaptcha - Upon choosing this option, the applicant will not be able to know when the validation takes places. It will be up to the form builder to decide when to trigger the validation.
The level of security for each validation is available under security preference in Google reCaptcha admin view.Google reCaptcha supports the following languages: https://developers.google.com/recaptcha/docs/language
To support this functionality this package includes the following:
Google reCaptcha component
This maestro native component can be used by form developers by adding it into the form structure where the reCaptcha UI will be displayed.
NOTE: that even the invisible reCaptcha type needs to have a placeholder in the form where potential notification messages or additional captcha checks requiring user actions will be displayed.
Dynamic data service (DDS): Google reCaptcha - verify
This DDS is called immediately as the client side reCaptcha verification token has been obtained from Google. To complete the verification process the token must be passed on the Transact server and verified by the Google backend API. The DDS uses the clients secret key and the token to do so. The result of the backend verification is then passed back into the web client in the same DDS call response.
The bellow diagram displays the sequence of events which occur at run time when using the google reCaptcha verification:
- Form is loaded in the web browser
- The user navigates to the page X - reCaptcha widget is rendered
- The user is "recognized"
- reCaptcha v2 - by clicking the "I am not a robot" checkbox
- Invisible - the recognition is triggered immediately when the widget is rendered (user navigated to the page/section where the reCpatcha widget is placed)
- When Google provisions a new token (also referred to as recaptcha response) the built in tokenCallback JS methods is called and the token is passed on it
- The token is immediately verified on the TM server
- tokenCallback calls the Google reCaptcha - Verify TM DDS
- The Google reCaptcha - Verify DDS requests the Google API to verify the token by providing the client's google reCaptcha secret key
- if Google responds with a successful verification result the DDS sets the "google.recaptcha.verified=true" submission property on the current Transaction
- the verification result is returned back into the form
- based on the server verification result one of the form's onSuccess or onFailure rules is executed
- The from developer can utilize and implement any of the listed TM services to perform a later server side check that the current Txn has been successfully reCaptcha verified be fetching the Txn "google.recaptcha.verified
" submission property set to "true"
Submission Data Validator
Dynamic Data Service
Submission Complete Processor
Any client who wishes to use the proposed Avoka Exchange reCaptcha component will need to use their own Google account and sign up for their own key pair as per the usual process described at https://developers.google.com/recaptcha/intro. Note that Google requires individual registration for different reCatpcha types. While the same google account can be used for multiple registrations, each will use a different set of site&secret keys to be configured on the web application (Avoka form).
More on obtaining Keys: http://www.google.com/recaptcha/admin
This package has the following compatibility requirements:
|5.0 or above
|5.0.0 or above
The Content Security Policy (CSP) response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via a HTTP Header, thereby protecting your solution from a range of vulnerability attacks.
script-src 'self' https://www.gstatic.com https://www.google.com; object-src 'none'
For more information see CSP on The Avoka Community
To install this package please walk through the following proceedure:
- Unzip the package to a directory on your computer
- Import each zip archive found in the
servicesfolder to Transact Manager under the Services >> All Services menu item.
- Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
- Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.
Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
- Import each archive found in the
librariesfolder to Maestro.
Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.
Use the following procedure to configure Google reCaptcha component in your form:
- Add the Google reCaptcha component onto your page.
In the Configuration section:
- Select the reCaptcha type: reCaptcha v2 or Invisible reCaptcha.
- Set the site key. (You should have Google site key specific to the reCaptcha type you selected before)
- Select the reCaptcha theme.
- Select the language key or leave it on default 'en'
- Change the progress message if required or remove it completely. It is recommended to remove the progress message when you use the Invisible ReCaptcha type.
- In the Rules section, add any processing rules to handle
- Verify you setup the Google reCaptcha service connection according to the instruction below.
NOTE: In order to bypass the recaptcha checks for functional tests, you can use Google's static test api keys pair. These can be find here.
Using the component in Transact applications
On top of the configuration described above the form developers can prevent enforcing the user to go through the reCaptcha verification by implementing a visibility rule on the widget. If the widget is hidden the verification is not enforced (required) nor executed. For example it might be desired that the reCaptcha verification is not required in subsequent form sessions upon a resume of a saved form when the user has already been verified in one of the previous form sessions. This would be a very standard scenario as its expected that saved anonymous forms are resumed after the user enters a save challenge question answer which would prevent any bots from accessing such transactions. It would be recommended not using the reCaptcha in other means of user authenticated sessions either.
The widget is implemented as "bindable" which means its value can be bound to a XML element in the submission payload. The value of the widget is the result of the verification processes. The value can be undefined/true/false.
undefined - the verification hasnt been executed yet
false - the last verification failed
true - the last verification was successfull
If the the recaptcha verification is required in every form session (fresh or resumed transactions) the form developer can keep the widget always dispalyed in the form however must ensure the "google.recaptcha.verified" submission property is reset (nullified) when resuming the saved form in the Form prefill or Form security filter services.
Version 1.1 May 14, 2019
- Enhanced to configure the site key without a need to re-build the applications when progressing to more advanced environments (test,stage,prod).
Note: Keep your site key before upgrading the Maestro library, after the upgrade, the site key must be set in service connections.
Version 1.0 Jul 20, 2018
- Baseline release.
Google reCaptcha component
You may add your own logic to handle the following rule types triggered by this component:
- On Success :
A form developer will be able to configure the onSuccess rule which will be auto-triggerred when the user has been successfully verified (server side included). The rule will provide a great placeholder for custom logic like:
- enable navigation through the form upon successful reCatpcha verification only
- make form blocks visible
- display notification messages about the verification process
- On Failure :
A form developer will be able to configure the onFailure rule which will be auto-triggerred when the verification process failed. The rule will provide a great placeholder for custom logic like:
- display notification messages about the verification process failure advising the user to try again/later
- make form blocks visible
The following rule helpers can be used when right-clicking on this component in a script editor:
- Execute Recaptcha
|Google reCaptcha Type
|Mandatory drop down with the below options. For more information go to: https://developers.google.com/recaptcha/docs/versions
|Optional text field - forces the widget to render in a specific language.For more information go to: https://developers.google.com/recaptcha/docs/language
|Google reCaptcha Theme.For more information go to: https://developers.google.com/recaptcha/docs/display#config
|Execute on widget init (Invisible only)
|This option is for Invisible reCaptcha only. When checked, reCaptcha will be triggered on widget init.
|Google reCaptcha verify progress message
|When the fetchSiteKey flag is set the service returns the Google site key.
|reCAPTCHA response token
|When there is a verification result from Google reCaptcha API. (
|The status of the service execution [
Successful execution will be denoted by a
DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
The following service connections are used by this package.
|Must point to Google reCaptcha API at: https://www.google.com/recaptcha/api/siteverify
|Must contain reCAPTCHA the secret key.
|Must contain the reCAPTCHA site key.