Конфигурирование CAPTCHA#

Поддерживаемые типы#

При работе Blitz Identity Provider можно использовать следующие типы CAPTCHA:

встроенная Yandex Smart Captcha,
встроенная Google reCAPTCHA v3,
внешняя CAPTCHA.

Каталог с конфигурацией CAPTCHA#

По умолчанию настройка всех CAPTCHA хранится внутри директории /etc/blitz-config в каталоге captchas.

При необходимости в параметре captchas-source -> dir файла конфигурации /usr/share/identityblitz/blitz-config/blitz.conf можно указать другой каталог хранения конфигураций CAPTCHA.

Примечание

Путь задается либо абсолютно, либо относительно директории /etc/blitz-config.

"captchas-source": {
    "dir": "captchas2"
}

Внутри директории хранения CAPTCHA находятся подкаталоги с настройками для каждой конкретной CAPTCHA. По умолчанию подкаталоги для встроенных CAPTCHA уже созданы:

yandexSmartCaptcha,
reCaptchaV3.

Вы можете создать новые подкаталоги для CAPTCHA типа yandexSmartCaptcha и reCaptchaV3 или добавить каталог для настройки внешней CAPTCHA.

Важно

Имя подкаталога CAPTCHA должно совпадать с системным именем (sysname) CAPTCHA, указанным в ее настройках.

Внимание

Системное имя CAPTCHA должно состоять из латинских букв, цифр и знака подчеркивания.

Внутри подкаталога каждой встроенной CAPTCHA лежит файл конфигурации CAPTCHA в формате формат ${sysname}.json.

Внутри подкаталога внешней CAPTCHA лежит ее файл конфигурации в формате ${sysname}.json и (опционально) подкаталог assets, в котором хранятся различные ресурсы (.js, .css и другие), необходимые для работы CAPTCHA.

Пример структуры директорий для CAPTCHA с системными именами: yandexSmartCaptcha, reCaptchaV3, customCaptchaV2.

-- captchas
  -- yandexSmartCaptcha
        yandexSmartCaptcha.json
  -- reCaptchaV3
        reCaptchaV3.json
  -- customCaptchaV2
     -- assets
       -- javascripts
          passwordCaptcha_v2.js
       -- stylesheets
          passwordCaptcha_v2.css
     customCaptchaV2.json

Файл конфигурации CAPTCHA#

Файл конфигурации CAPTCHA ${sysname}.json в первых строках может содержать комментарии (преамбулу), после которых помещается конфигурация CAPTCHA в формате json. Если в разделе есть поле __enc_alg с указанием алгоритма шифрования, то все строковые поля в этом блоке, кроме служебного поля __enc_alg, считаются секретными.

Внимание

Секретные значения хранятся в зашифрованном состоянии. Если их внести в файл конфигурации в незашифрованном виде, то при старте сервера они будут зашифрованы указанным алгоритмом.

Примечание

На момент написания документации поддержан только текущий алгоритм со значением default. В дальнейшем будет поддержана возможность нескольких алгоритмов шифрования, а также ротация ключей шифрования. Напишите нашим экспертам по адресу support@idblitz.ru, если данный функционал вам нужен.

Тип CAPTCHA задается в конфигурации в поле typ:

{
  ...
  "typ": "custom"
}

Возможные значения typ:

yandexSmartCaptcha - для встроенной Yandex Smart Captcha.
reCaptchaV3 - для встроенной Google reCAPTCHA v3.
custom - внешняя CAPTCHA.

Yandex Smart Captcha#

При настройке Yandex Smart Captcha можно задать любое системное имя, а также создать несколько CAPTCHA такого типа.

Совет

По умолчанию встроенная CAPTCHA такого типа уже создана с именем yandexSmartCaptcha.

Пример yandexSmartCaptcha.json#

{
  "check" : {
    "validateDomain" : false
  },
  "secretKey" : {
    "__enc_alg" : "default",
    "value": "{$}2Aw1rkce8QEuaHZTsC/0F/KeVOThB/17w0Taat/N/LJnzafBNB4lT8CCWmfatT3/sQNUAHpcmhpgO83UWhOfAdEe+/LIpAqSY7zKhHkvV1Ogmlk6QqWuWg==",
  },
  "jsConf" : {
    "test" : false,
    "hl" : "ru",
    "shieldPosition" : "bottom-right",
    "invisible" : true,
    "hideShield" : false,
    "webview" : false,
    "sitekey" : "ysc1_Bff7fDvtAKsxtenvQWULIDkZKPbTa0ndceLOM55Db757da07"
  },
  "typ" : "yandexSmartCaptcha"
}

Подробное описание полей приведено здесь.

Поля для настройки интеграции с Blitz Identity Provider:

check.validateDomain - включает/выключает проверку соответствия домена Blitz Identity Provider и поля host в ответе сервера CAPTCHA.
jsConf- задает параметры функции window.smartCaptcha.render. Обязательным полем является только sitekey.

Google reCAPTCHA v3#

При настройке Google reCAPTCHA v3 можно задать любое системное имя, а также создать несколько CAPTCHA такого типа.

Совет

По умолчанию встроенная CAPTCHA такого типа уже создана с именем reCaptchaV3.

Пример reCaptchaV3.json#

{
  "check" : {
    "validateDomain" : false,
    "minScore" : 0.8
  },
  "secretKey" : {
    "__enc_alg" : "default",
    "value": "{$}AV+eqq3gaOSUnhOsuxdn7AlhfFp+/JV1snpxIb19vnIgifIewLaPTeuHPH0ZSv95TrQ2ecpMjrvCDAoWrfGaq04/KQR7wPH9"
  },
  "jsConf" : {
    "sitekey" : "6Lch184ZAAAAAHXxgWPtmYyKXW8TZkKaKbSqbdHf"
  },
  "typ" : "reCaptchaV3"
}

Поля для настройки интеграции с Blitz Identity Provider:

check.validateDomain - включает/выключает проверку соответствия домена Blitz Identity Provider и поля hostname в ответе сервера CAPTCHA.
check.minScore - задает минимальное значение поля score в ответе сервера CAPTCHA, при котором проверка будет считаться успешной.

Внешняя CAPTCHA#

Пример customCaptchaV2.json#

{
  "operations": [
    {
      "call": {
        "headers": [
          {
            "name": "accept",
            "value": "application/json"
          },
          {
            "name": "SYSTEM",
            "value": "${cfg.system}"
          },
          {
            "name": "SYSTEM-TOKEN",
            "value": "${cfg.systemToken}"
          },
          {
            "name": "Content-Type",
            "value": "application/json"
          },
          {
            "name": "Authorization",
            "value": "Bearer ${ctx.bearerToken}"
          }
        ],
        "method": "post",
        "body": {
          "json": "{\"uid\": \"${ste.uid}\",\"ttl\": ${cfg.ttl},\"type\": \"${cfg.type}\",\"solution\": \"${ocp.solution}\"}",
          "contentType": "application/json"
        },
        "url": "https://<DOMAIN>/captcha/2.0.0/check"
      },
      "sysname": "check",
      "check": {
        "errRegExp": {},
        "okRegExp": {
          "error.error": "0"
        }
      },
      "newState": {
        "uid": "${rsp.data.uid-}"
      }
    },
    {
      "call": {
        "headers": [
          {
            "name": "accept",
            "value": "application/json"
          },
          {
            "name": "SYSTEM",
            "value": "${cfg.system}"
          },
          {
            "name": "SYSTEM-TOKEN",
            "value": "${cfg.systemToken}"
          },
          {
            "name": "Content-Type",
            "value": "application/json"
          },
          {
            "name": "Authorization",
            "value": "Bearer ${ctx.bearerToken}"
          }
        ],
        "method": "post",
        "body": {
          "json": "{ \"ttl\": ${cfg.ttl},\"type\": \"${cfg.type}\"}",
          "contentType": "application/json"
        },
        "url": "https://<DOMAIN>/captcha/2.0.0/create"
      },
      "sysname": "create",
      "newState": {
        "uid": "${rsp.data.uid-}"
      }
    },
    {
      "call": {
        "headers": [
          {
            "name": "accept",
            "value": "application/json"
          },
          {
            "name": "SYSTEM",
            "value": "${cfg.system}"
          },
          {
            "name": "SYSTEM-TOKEN",
            "value": "${cfg.systemToken}"
          },
          {
            "name": "Content-Type",
            "value": "application/json"
          },
          {
            "name": "Authorization",
            "value": "Bearer ${ctx.bearerToken}"
          }
        ],
        "method": "post",
        "body": {
          "json": "{\"uid\": \"${ste.uid}\", \"ttl\": ${cfg.ttl},\"type\": \"${cfg.type}\"}",
          "contentType": "application/json"
        },
        "url": "https://<DOMAIN>/captcha/2.0.0/refresh"
      },
      "sysname": "refresh"
    }
  ],
  "js": {
    "module": "javascripts/passwordCaptcha_v2.js",
    "conf": {
      "css": "stylesheets/passwordCaptcha_v2.css"
    }
  },
  "typ": "custom",
  "secretParams" :{
    "__enc_alg" : "default",
    "systemToken": "{$}ZiOShsBV20lZZGj6LcD7G5VYCaUw7fX+3RICSFZF9dkYv40D+hmiQg==",
    "system": "{$}AFvhqaspNeECCtKNQaOz4Lg7QlztQa4Tfk28VNrOS6+twAHW40l3xA==",
  },
  "params": {
    "ttl": 600.0,
    "type": "math"
  }
}

Поля:

operations - список операций, которые могут быть инициированы из javascript CAPTCHA. Каждая операция имеет:
- sysname - системное имя;
- call - запрос к серверу CAPTCHA со следующими параметрами:
  - url - URL запроса;
  - method - метод запроса: GET или POST;
  - headers - заголовки запроса (опционально);
  - body - тело запроса (опционально). Поле contentType может принимать следующие возможные значения:
    - application/json - значение тела (в параметре json) в строковом формате JSON;
    - application/x-www-form-urlencoded - в этом случае в поле params задаются параметры тела в виде: {«имя_параметра1» : «значение_параметра1», «имя_параметра2» : «значение_параметра2» …};
- newState - новое состояние CAPTCHA (опционально);
- check - условия проверки ответа сервера CAPTCHA (опционально) с полями:
  - okRegExp - условия успешной проверки CAPTCHA. Содержит список проверяемых полей из ответа CAPTCHA и регулярных выражений, которым они должны соответствовать. Проверка CAPTCHA считается успешной, если выполнены условия для всех перечисленных полей.
  - errRegExp - условия неуспешной проверки CAPTCHA. Содержит список проверяемых полей из ответа CAPTCHA и регулярных выражений, которым они должны соответствовать. Проверка CAPTCHA считается неуспешной, если выполнены условия для всех перечисленных полей.
js - параметры клиентской части CAPTCHA:
- module - содержит относительный путь в каталогу assets к javascript CAPTCHA;
- conf - содержит список параметров, передаваемых при инициализации javascript CAPTCHA.
Примечание

Здесь также могут быть параметры, содержащие путь к ресурсу CAPTCHA из каталога assets.
typ - тип CAPTCHA, для внешней CAPTCHA проставляется значение custom;
params - список параметров, используемых при вычислении параметров операций;
secretParams - список параметров с секретными значениями, используемых при вычислении параметров операций;

При вычислении параметров url, headers, body каждого запроса к серверу CAPTCHA (operations -> call) могут использоваться подстановки со следующими префиксами:

cfg. - конфигурационные параметры из раздела params и secretParams;
ctx. - параметры контекста запроса: lang, remoteAddress;
ocp. - параметры из тела запроса, сформированного в javascript CAPTCHA;
och. - заголовки запроса, сформированного в javascript CAPTCHA;
ste. - параметры текущего состояния CAPTCHA.

При формировании текущего состояния CAPTCHA дополнительно могут использоваться подстановки с префиксом rsp. - поля из json-тела ответа сервера CAPTCHA.

Включение отображения CAPTCHA#

CAPTCHA может отображаться пользователю при регистрации и восстановлении доступа, а также при входе по паролю, коду из SMS и через внешнего поставщика. Подробнее.