Introduction

This guide walks you through the steps involved in implementing a CAPTCHA as an add-on along with the ShieldSquare service. This can be used as per the user’s convenience, but the basic structure to integrate it with the ShieldSquare service must be followed as shown below. For reference we have specified the steps to implement Google’s ReCAPTCHA along with the service.

Note

This guide requires a complete working integration of the connectors or server modules.

Prerequisites

Activate ShieldSquare service in Active mode
Configure the rules from your dashboard for the ShieldSquare service to respond with the CAPTCHA response code (2).
If you plan to use Google’s ReCAPTCHA then register your site's domain at the Google reCAPTCHA website to obtain your API keys: https://www.google.com/recaptcha/intro/index.html .You will be given two keys, a private key for calls between the customer web server and the reCAPTCHA service, and a public key for calls between the user and the customer's web server.

Set of files that are provided in Active Mode CAPTCHA Kit.

Sample Active Mode code
Sample CAPTCHA Page

The PHP kit can be downloaded from following link:

The implementation process has been split into two parts:

Changes to be made on the Requested Page
Changes to be made on the CAPTCHA Page

1. Changes to be made on the Requested Page

When implementing a CAPTCHA Page, always maintain a session variable, let's say “captchaResponse” [any name can be used]. This is used to identify whether the request for the page is made for the first time or not. The values for the “captchaResponse” are listed below.

captchaResponse	Implication
Null or Undefined	If the value of the session variable is null or undefined, it means that it was not set in the session, and that the user is requesting the page for the first time.
1	If the value of the session variable is “1” it means that the user is returning to the page after successfully solving the CAPTCHA.
2 (Any value other than 1 can be used)	If the value of the session variable is “2” it means that the user is trying to access the page after failing the CAPTCHA challenge.

Before calling the ShieldSquare API, check the value of the session variable “captchaResponse”. If the value of this attribute is not set, or if it is not equal to ‘1’: Call the ShieldSquare API with the call type value as ‘1’ as shown below:

//Check for the session variable & make the ShieldSquare API callif(!isset($_SESSION["captchaResponse"])){//set the calltype value as 1
$shieldsquare_calltype=1;

$shieldsquare_response = shieldsquare_ValidateRequest($shieldsquare_userid,
$shieldsquare_calltype);
}

When the response code received from the ShieldSquare API call is ‘2’ redirect the user to the CAPTCHA page. If the “captchaResponse” is equal to ‘1’ call the ShieldSquare API with the call type value ‘5’. This is just to let the ShieldSquare service know that the CAPTCHA has been solved successfully. This call will be an asynchronous call (provided your website platform supports asynchronous calls), and so there will be no waiting time for the response. The response to this call will always be Allow (0).

//Set the calltype value as 5
$shieldsquare_calltype=5;//Make the Shield Square API call
$shieldsquare_response = shieldsquare_ValidateRequest
($shieldsquare_userid, $shiseldsquare_calltype);
Sample code for Active Mode

<?php
include 'ss2.php';

$shieldsquare_userid   ="";// Enter the UserID of the user//check if the value of captchaResponse is set in the sessionif(!isset($_SESSION["captchaResponse"])){//set calltype as 1
        $shieldsquare_calltype =1;
        $shieldsquare_response=shieldsquare_ValidateRequest($shieldsquare_userid,
$shieldsquare_calltype);}else{
        $shieldsquare_calltype =5;

        $shieldsquare_response = shieldsquare_ValidateRequest($shieldsquare_userid, 
$shieldsquare_calltype);//Unset the session variable
unset($_SESSION["captchaResponse"]);
unset($_SESSION["currentPagename"]);}if($shieldsquare_response->responsecode ==0)
        echo "Allow the user request";

elseif ($shieldsquare_response->responsecode ==2){//setting the current page name to the session for later use
        $current_page =basename($_SERVER['PHP_SELF']);
        $_SESSION["currentPagename"]= $current_page;//Redirect to the CAPTCHA page
        header("Location:DisplayCaptcha.php");}
elseif ($shieldsquare_response->responsecode ==-1){
        echo "Curl Error - ". $shieldsquare_response->reason ."
";
        echo "Please reach out to ShieldSquare support team for assistance 
";
        echo "Allow the user request";}?>

2. Changes to be made in the CAPTCHA page

Make a call to the ShieldSquare API with the value of calltype value as ‘4’

//set the calltype value as 4 
$shieldsquare_calltype =4;//Make the call to the API
$shieldsquare_response = shieldsquare_ValidateRequest($shieldsquare_userid, $shieldsquare_calltype);

Note

This call will be an asynchronous call (provided your website’s platform supports asynchronous call) and so there will be no waiting time for the response. The response to this call will always be Allow (0). This call is made to let the ShieldSquare service know that a CAPTCHA page has been displayed.

The complete sample code for CAPTCHA page is shown below

Sample CAPTCHA page code
<?php
//Init CAPTCHA Variables
include 'ss2.php';//path to ss2 php file

$siteKey="your-sitekey-goes-here";//Enter your sitekey obtained from reCaptcha Vebsite
$secret="your-s3cr3t-key-goes-here";// Enter your secret key obtained from reCaptcha Vebsite

$lang ='en';//Language of website here -- See Google's ReCAPTCHA V2 for options?><!--The GET Request CAPTCHA PAGE (StylesandIncludes)--><html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>ShieldSquare reCAPTCHA Page</title><link rel="shortcut icon" href="https://cdn.perfdrive.com/icons/favicon.png" type="image/x-icon"/><style type="text/css">
            body {
                margin:1em5em05em;
                font-family: sans-serif;}
            fieldset {
                display:inline;
                padding:1em;}</style></head><body align="center"><a href="//www.shieldsquare.com" target="_blank"><img src="https://cdn.perfdrive.com/icons/shieldsquarelogo.png"></a><hr><h1>SuspiciousActivityDetected</h1><?php
    //making a call to Shieldsquare server that CAPTCHA is shown
    $shieldsquare_userid   ="";// Enter the UserID of the user
    $shieldsquare_calltype =4;
    $shieldsquare_response = shieldsquare_ValidateRequest($shieldsquare_userid, $shieldsquare_calltype);?><?php
    if(isset($_POST['g-recaptcha-response'])){
        $response = getCurlData("https://www.google.com/recaptcha/api/siteverify?secret=".$secret."&response=".$_POST['g-recaptcha-response']);
    $response = json_decode($response,true);if($response["success"]===true){
        $redirPage = $_COOKIE["currentPagename"];
        setcookie(md5("captchaResponse"),md5("1".$redirPage.$_SERVER[$shieldsquare_config_data->_ipaddress].$shieldsquare_config_data->_sid),time()+60*60,"/");
        header("Location:".$redirPage);exit();}else{
        header("Location:".$_SERVER["PHP_SELF"]);exit();}}?><!--TheFormDisplay--You can Customizethis form forYourself!--><p>Complete the reCAPTCHA then submit the form.</p><fieldset><legend>SolveCaptcha</legend><form action="<?php $_SERVER['PHP_SELF']; ?>"  method=POST><div class="g-recaptcha" data-sitekey="<?php echo $siteKey; ?>"></div><script type="text/javascript"
                    src="https://www.google.com/recaptcha/api.js?hl=<?php echo $lang; ?>"></script><br><input type=SubmitValue="GO"/></fieldset></form><br><br><br><br><hr><br><footer><small>©Copyright2015,AllRightsReserved.KaalbiTechnologiesPvt.Ltd.</small></footer></body></html><?php
function getCurlData($url){
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
    curl_setopt($curl, CURLOPT_TIMEOUT,10);
    curl_setopt($curl, CURLOPT_USERAGENT,"Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2.16) Gecko/20110319 Firefox/3.6.16");
    $curlData = curl_exec($curl);
    curl_close($curl);return $curlData;}?>

Radware Bot Manager Integration Portal

ShieldSquare CAPTCHA Implementation guide

Introduction

1. Changes to be made on the Requested Page

2. Changes to be made in the CAPTCHA page