CS

Google reCAPTCHA implementation

Home / Documentation / Administrator guide /

Google reCAPTCHA implementation

CS

Google reCAPTCHA is a service provided by Google that protects forms against spam and automated abuse — it evaluates the behaviour of the visitor and tells a real user from a robot. In NET Genium it is used to protect public forms, that is forms accessible to anonymous users (a contact form, an enquiry, a registration).

The protection always consists of two parts: an HTML control inserts the verification code into the form using the server function “GOOGLECAPTCHA” or “GOOGLECAPTCHAINVISIBLE”, and the script of a button verifies the response on the server side using the server function “EVALGOOGLECAPTCHA”. Without the second part the protection is only apparent — a robot that submits the form without interacting with the Google service is not stopped in any way.

NET Genium supports keys of the Challenge (v2) and Invisible (v2) type. The result of the verification is only the information whether the check passed or not. Keys of the score type (reCAPTCHA v3), which return a numeric expression of the probability that the form was submitted by a human, are not supported.

The obsolete function “CAPTCHA” (a verification code rendered into an image) is not used for new implementations — automated tools read it with a high success rate and it is inaccessible to visually impaired users.

1. Two variants of the protection

  • Invisible reCAPTCHA badge — the check runs “invisibly” in the background of the page, without any interaction of the user. Only the badge of the service is displayed in the corner of the window. The implementation requires two buttons — a visible button that starts the check, and a hidden button that performs the server-side verification once Google responds.
  • Google reCAPTCHA “I'm not a robot” Checkbox — the user ticks the “I'm not a robot” checkbox. The implementation requires one button in which the verification is performed.

The type of protection is chosen as early as when the keys are created (see the following chapter) — a key created for one variant cannot be used for the other.

2. Creating the Google reCAPTCHA keys

A Google account is required to create the keys. According to the current price list of Google, the first 10,000 verifications per month are free of charge; beyond that limit fees are charged.

  1. Open https://console.cloud.google.com/projectselector2/security/recaptcha and sign in with your Google account.
  2. If you do not have a project yet, create one with the “Create project” button. Otherwise select the project in which you want to create the key.
  3. Click the “Create key” button and fill in the form:
    1. “Display name” — preferably the name of your domain (for example www.netgenium.com)
    2. “Application type” — select “Web”
    3. add the domain with the “Add domain” button (for example www.netgenium.com)
  4. Depending on the required variant of the protection:
    1. Invisible badge — click “Create key”
    2. “I'm not a robot” Checkbox — click “Next step (optional)”, tick “Will you use challenges?” and only then click “Create key”
  5. Copy the “Site key” from the header of the created key — it is stated after the “ID:” text.
  6. On the “Integration” tab click “Integrate with a third-party service or plugin” and copy the “Secret key” from the pop-up window.
  7. Save both keys — the “Site key” is written into the HTML control, the “Secret key” into the script of the button.

The “Secret key” is not displayed anywhere else in the console — the only place that offers it is the pop-up window on the “Integration” tab.

3. Implementation of the Invisible reCAPTCHA badge

3.1. The button that starts the check

  • Create a new “Button” control in the edit form.
  • On the “General” tab enter the name of the button, for example “Send enquiry”.
  • On the “Event” tab write the javascript function “evalGoogleCaptcha();” into the “Client” field and save the button.

By pressing the button the user triggers the check by the Google service, which returns a response telling whether it is a robot or not.

3.2. The hidden button that verifies the response on the server

  • Create a second “Button” control.
  • On the “General” tab enter the name of the button, for example “Send enquiry – step 2”, tick “Hidden button” and save the button.
  • On the “Event” tab tick “Script” and click “Edit script”.
  • Insert a comment on the first line of the script and write into it a call of the “EVALGOOGLECAPTCHA” function with your “Secret key” and with an error message.
EVALGOOGLECAPTCHA(6Lda_JIUAAAAANloD9-zLrfSHkyeAR3wBLbrqLQI, "Sorry, we think you're a robot...")
  • Add the remaining steps of the script that are to be performed after a successful verification — sending an e-mail, a thank-you message and so on. If the verification does not pass, the script is interrupted with the error message and the remaining steps are not performed.

The “EVALGOOGLECAPTCHA” function is evaluated only on a line of the comment type. Written on any other line of the script it is not performed and the form stays unprotected.

3.3. Inserting the GOOGLECAPTCHAINVISIBLE function

  • Create a new “HTML” control.
  • On the “General” tab write a call of the “GOOGLECAPTCHAINVISIBLE” function with your “Site key” and with the identifier of the hidden button from the previous step.
GOOGLECAPTCHAINVISIBLE(6Lda_JIUAAAAAMaSHupdzEhcvAmz06oMZ1Qm4yoV, BT216)

The identifier of the button consists of “BT” and the database ID of the button; the ID is displayed when you hover the mouse cursor over the pencil icon (“Edit Button”) of the button. The hidden button is started by NET Genium itself once the response from Google is received.

The function has two more optional parameters — the address of the script of the service (the default is “https://www.recaptcha.net/recaptcha/api.js”, an address available even in networks that block the google.com domain) and the position of the badge with the values “bottomright”, “bottomleft” and “inline”.

4. Implementation of the “I'm not a robot” Checkbox

4.1. Inserting the GOOGLECAPTCHA function

  • Create a new “HTML” control in the edit form.
  • On the “General” tab write a call of the “GOOGLECAPTCHA” function with your “Site key”.
GOOGLECAPTCHA(6LemsJMUAAAAAECVTRA6PGMVjtFLXlxT7e4mIwqd)

The optional second parameter is the address of the script of the service; if it is not stated, “https://www.google.com/recaptcha/api.js” is used.

4.2. The button that verifies the response on the server

  • Create a new “Button” control and enter its name on the “General” tab, for example “Send enquiry”.
  • On the “Event” tab tick “Script” and click “Edit script”.
  • Insert a comment on the first line of the script and write into it a call of the “EVALGOOGLECAPTCHA” function with your “Secret key” and with an error message.
EVALGOOGLECAPTCHA(6LemsJMUAAAAAMNjeaAq5Zn-vKnVTK0WeloxKrgu, You have not ticked the CAPTCHA field)
  • Add the remaining steps of the script that are to be performed after a successful verification.

Unlike the Invisible variant, a single button is enough here — ticking the “I'm not a robot” checkbox runs the check before the form is submitted.

5. Operation and debugging

  • Unsuccessful attempts are written into the “Warnings” log in the “Logs” directory of the given NET Genium instance (for example “C:\inetpub\wwwroot\netgenium\Logs”). The entry contains the used “Secret key”, the user, the address of the page and the reason — a missing response from the service (the Invisible variant logs evalGoogleCaptcha(); was not called, the Checkbox variant I am not a robot was not clicked), or the error returned by the verification endpoint.
  • In the test mode of the script designer the verification is not performed — the “Run script” button skips the “EVALGOOGLECAPTCHA” function. Always test the protection by submitting a real form.
  • If the connection to the verification endpoint fails (“https://www.google.com/recaptcha/api/siteverify”), the script is interrupted with the same error message as an unsuccessful verification and the detail is written into the “Warnings” log.
  • If the server is behind a proxy server, state its address as the third, optional parameter of the “EVALGOOGLECAPTCHA” function — the verification request then goes through it.
EVALGOOGLECAPTCHA(6LemsJMUAAAAAMNjeaAq5Zn-vKnVTK0WeloxKrgu, You have not ticked the CAPTCHA field, http://proxy:8080)

6. Administration of the created keys

  1. Open https://console.cloud.google.com/projectselector2/security/recaptcha and sign in with the Google account under which you created the keys.
  2. Open the project in which you created the keys and scroll down to the “reCAPTCHA keys” section.
  3. The “Key details” button opens the detail of the key — in the middle there is a chart with the usage statistics and in the upper right corner the “Edit key” and “Delete this key” buttons for editing or deleting the key.

A detailed description of the “GOOGLECAPTCHA”, “GOOGLECAPTCHAINVISIBLE” and “EVALGOOGLECAPTCHA” server functions is provided in the separate guide Server functions.