CAPTCHA#

To display the CAPTCHA service for logins and passwords you need to create a configuration file and load the required files (CSS and JS).

Changes in the configuration file must be done:

in the blitz.prod.local.idp.captcha settings block. An example of a setting entry is shown below:

"captcha" : {
    "exampleCaptcha": {
        "operations": [
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "post",
                    "url": "https://captcha.example.com/captcha/1.0.0/check?uniqueFormHash=${ste.uniqueFormHash}&code=${ocp.code}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "check": {
                    "errRegExp": {},
                    "okRegExp": {
                        "error": "0"
                    }
                },
                "name": "check",
                "newState": {
                    "uniqueFormHash": "${rsp.result.uniqueFormHash-}"
                }
            },
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "get",
                    "url": "https://captcha.example.com/captcha/1.0.0/create?type=${cfg.type}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "name": "create",
                "newState": {
                    "uniqueFormHash": "${rsp.result.uniqueFormHash-}"
                }
            },
            {
                "call": {
                    "headers": [
                        "accept:application/json",
                        "Authorization:Bearer ${cfg.bearerToken}"
                    ],
                    "method": "post",
                    "url": "https://captcha.example.com/captcha/1.0.0/refresh?uniqueFormHash=${ste.uniqueFormHash}&type=${cfg.type}&options[system]=${cfg.system}&options[token]=${cfg.token}"
                },
                "name": "refresh"
            }
        ],
        "plainParams": {
            "type": "arithmetic"
        },
        "secureParams": {
            "bearerToken": "<access_token>",
            "system": "<system_id>",
            "token": "<system_token>"
        }
    }
}

This block contains parameters for calling three methods of CAPTCHA service (create, check, refresh), as well as secret parameters - access token (bearerToken), system identifier (system), and system token (token).

in the block of login settings blitz.prod.local.idp.password. Inside this block add captcha block and configure it according to the example:

"captcha" : {
  "enabled": true,
  "initJs": "require(['https://demo.reaxoft.ru/themes/default/assets/js/passwordCaptcha.js', 'captcha-conf'], function(captcha, conf){ captcha(conf, 'https://demo.reaxoft.ru/themes/default/assets/css/passwordCaptcha.css');});",
  "mode": {
    "type": "always_on"
  },
  "name": "exampleCaptcha"
}

In this block you should configure the following parameters:

enabled - indicates whether CAPTCHA is enabled or not (true/false);
initJs - contains links to the Javascript and CSS loaded on the login page and required to display/invoke CAPTCHA on login page;
mode - CAPTCHA display mode, the following modes are provided:
- always_on - CAPTCHA is always displayed;
- on_header - CAPTCHA is displayed if the request has the header specified in the name parameter and the value specified in the value parameter.
- by_brute_force_protection - A CAPTCHA is displayed if Blitz Identity Provider has detected password brute force on a specific account or mass password brute force on all accounts.

When using by_brute_force_protection mode, it is required to additionally create bruteForceProtection settings block with the following settings in blitz.prod.local.idp.password block:

disabled - whether the protection is disabled or not (true/false);
captcha - whether to use the CAPTCHA test when the protection is triggered (true/false);
delay - login delay time in seconds (applies if CAPTCHA usage is disabled);
block system in the thresholds setting - if system-level protection is required (protection against brute force on different logins). The settings are:
- minAttemptsToActivate - minimum number of passed inputs to activate the protection mechanism based on the system statistics (100 inputs by default);
- timeWindowInMin - time window for collecting statistics on the ratio of successful and unsuccessful inputs in minutes, must be even (100 minutes by default);
- failedAttemptsPercent, the turnOff setting is the threshold for turning off automatic protection, in percent;
- failedAttemptsPercent, the turnOn setting is the threshold for turning on automatic protection, in percent.
- forced - enable forced protection for all (true/false).
system block in the thresholds setting - if protection at the level of individual users is required (protection against password mining for a particular user). The settings are specified:
- ttlInSec - the period for which the counter of unsuccessful logins by user is accumulated in seconds (default is 3600 seconds);
- failedAttempts, the turnOn setting is the number of invalid logins per period after which protection will be enabled for the account.

Example of bruteForceProtection block settings (only user-level protection is enabled):

"bruteForceProtection" : {
    "delay" : 0,
    "captcha" : true,
    "disabled" : false,
    "thresholds" : {
        "user" : {
            "failedAttempts" : {
                "turnOn" : 5
            },
            "ttlInSec" : 3600
        }
    }
}

Example of bruteForceProtection settings (user-level and system-level protection enabled):

"bruteForceProtection" : {
    "disabled": false,
    "delay" : 0,
    "captcha" : true,
    "thresholds" : {
        "system" : {
            "minAttemptsToActivate": 1000,
            "timeWindowInMin": 180,
            "failedAttemptsPercent" : {
                "turnOff" : 20,
                "turnOn" : 30
            },
            "forced" : false
        },
        "user" : {
            "ttlInSec": 3600,
            "failedAttempts" : {
                "turnOn" : 5
            }
        }
    }
}

If you use Google’s reCAPTCHA v3 service as a CAPTCHA, you must:

set the following settings in blitz.prod.local.idp.captcha:

"captcha" : {
  "reCAPTCHAv3" : {
    "operations" : [
      {
        "call" : {
          "headers" : [],
          "method" : "post",
          "url" : "https://www.google.com/recaptcha/api/siteverify?secret=${cfg.secret}&response=${ocp.response}"
        },
        "check" : {
          "errRegExp" : {},
          "okRegExp" : {
            "score" : "1\\.0|0\\.(5|6|7|8|9)",
            "success" : "true"
          }
        },
        "name" : "verify"
      }
    ],
    "plainParams" : {
      "sitekey" : "SITE_KEY"
    },
    "secureParams" : {
      "secret" : "SITE_SECRET"
    }
  }
}

Instead of SITE_KEY and SITE_SECRET you should fill in the values obtained when registering Google reCAPTCHA v3 on the site https://g.co/recaptcha/v3. You should also adjust the value in the score parameter - set the required threshold for successful passing of the check (in the example, the threshold is set not lower than 0.5).

set the following settings in blitz.prod.local.idp.password.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the confirmation page for linking a user account to an account from an external identity provider, you must set the following settings in blitz.prod.local.idp.externalIdps.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the user registration page, you must set the following settings in blitz.prod.local.idp.provisioning.registration.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}

To add a CAPTCHA to the password recovery page, you must set the following settings in blitz.prod.local.idp.provisioning.recovery.captcha:

"captcha" : {
  "mode" : {
    "_name" : "X-Captcha-Check",
    "_value" : "true",
    "_type" : "on_header",
    "type" : "always_on"
  },
  "enabled" : true,
  "initJs" : "require(['/blitz/assets/blitz-common/javascripts/recaptcha_v3.js', 'captcha-conf'], function(captcha, conf){ captcha(conf);});",
  "name" : "reCAPTCHAv3"
}