Process Flow

The bellow diagram displays the sequence of events which occur at run time when using the google reCaptcha verification:

1. Form is loaded in the web browser
2. The user navigates to the page X - reCaptcha widget is rendered
3. The user is "recognized"
   1. reCaptcha v2 - by clicking the "I am not a robot" checkbox
   2. Invisible - the recognition is triggered immediately when the widget is rendered (user navigated to the page/section where the reCpatcha widget is placed)
   The widget requests a new recaptcha token from the Google API
4. 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
5. The token is immediately verified on the TM server
   1. tokenCallback calls the Google reCaptcha - Verify TM DDS
   2. The Google reCaptcha - Verify DDS requests the Google API to verify the token by providing the client's google reCaptcha secret key
   3. if Google responds with a successful verification result the DDS sets the "google.recaptcha.verified=true" submission property on the current Transaction
   4. the verification result is returned back into the form
6. based on the server verification result one of the form's onSuccess or onFailure rules is executed
7. 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
   Saved Processor
   Dynamic Data Service
   Submission Complete Processor

Licensing

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

Compatibility

This package has the following compatibility requirements:

CSP Configuration

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.

By default, Avoka Transact has strict CSP settings configured so these will likely need to be modified in order to enable the Google reCaptcha JavaScript API integration.

You can configure CSP settings in Transact Manager at a system wide level via the 'Form Submission Access Controller' service, or at an Organization level in the Security tab.

https://www.google.com

https://www.gstatic.com

script-src 'self' https://www.gstatic.com https://www.google.com; object-src 'none'

For more information see CSP on The Avoka Community

Installation Instructions

To install this package please walk through the following proceedure:

1. Unzip the package to a directory on your computer
2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
4. 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.

5. Import each archive found in the libraries folder 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.

Usage Instructions

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'
  • if the reCaptcha type is Invisible, you can thick the option Execute on widget init (Invisible only) to make the reCaptcha call on rendering the page, otherwise manually call the JavaScript method when required grecaptcha.execute();
  • 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 On Success, On Failure events.
• 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.

Release Notes

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.