Creating a CAPTCHA

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

1. View the description of the CLI command for creating a CAPTCHA:

   yc smartcaptcha captcha create --help
   

2. Create a CAPTCHA:

   yc smartcaptcha captcha create \
     --name <captcha_name> \
     --turn-off-hostname-check \
     --allowed-site <first_host>,<second_host> \
     --style-json '<captcha_appearance>' \
     --pre-check-type <main_challenge_type> \
     --challenge-type <additional_challenge_type> \
     --complexity <challenge_difficulty> \
     --security-rules-file <path_to_file_with_options>.yaml \
     --override-variants-file <path_to_file_with_rules>.yaml
   

   Where:

   • --name: CAPTCHA name.

   • --turn-off-hostname-check: Disable domain check. This is an optional parameter.

   • --allowed-site: List of hosts as IP addresses or domain names. without http/https or / at the end, e.g., example.com. The CAPTCHA will also be valid for all subdomains of the specified domain names. This is an optional parameter.

   • --style-json: Appearance of the challenge window and other elements, in JSON format. For more details, see the JSON generated using the management console. This is an optional parameter.

   • --pre-check-type: Type of the default main challenge the user will get. The possible values are:

     • CHECKBOX: Checkbox.
     • SLIDER: Slider.

   • --challenge-type: Type of the default additional challenge the user will get. The possible values are:

     • IMAGE_TEXT: Text recognition.
     • SILHOUETTES: Silhouettes.
     • KALEIDOSCOPE: Kaleidoscope.

   • --complexity: Default challenge difficulty. The possible values are:

     • EASY: Simple challenge.
     • MEDIUM: Medium level challenge.
     • HARD: Difficult challenge.
     • FORCE_HARD: Difficult challenge with an additional question. The user is required to solve an additional challenge, regardless of the results of the main one.

     Note

     The feature of challenge options and show rules is at the Preview stage.

   • --override-variants-file: Path to a YAML file with challenge options. This is an optional parameter.

     Example of a file with challenge options

     - uuid: <option_1_ID>
       description: <option_1_description>
       complexity: <challenge_difficulty>
       pre_check_type: <main_challenge>
       challenge_type: <additional_challenge>
     - uuid: <option_2_ID>
       description: <option_2_description>
       complexity: <challenge_difficulty>
       pre_check_type: <main_challenge>
       challenge_type: <additional_challenge>
     

     Where:

     • uuid: Unique ID of the challenge option.
     • description: Challenge option description.
     • complexity: Difficulty level of the challenge the user will get.
     • pre_check_type: Type of the main challenge the user will get.
     • challenge_type: Type of the additional challenge the user will get.

   • --security-rules-file: Path to a YAML file containing the rules for incoming traffic that will determine which CAPTCHA option to show. This is an optional parameter.

     Example of a file with rules for incoming traffic

     - name: <rule_1_name>
       priority: "<rule_1_priority>"
       description: <rule_1_description>
       override_variant_uuid: <challenge_option_ID>
       condition:
         host:
           hosts:
             - exact_match: example.com
             - exact_match: example.net
     - name: <rule_2_name>
       priority: "<rule_2_priority>"
       description: <rule_2_description>
       override_variant_uuid: <challenge_variant_ID>
       condition:
         source_ip:
           geo_ip_match:
             locations:
               - ru
               - kz
     

     Where:

     • name: Rule name.

     • priority: Rule priority, from 1 to 999999.

       Rules are checked in ascending priority order, starting from 1, 2, etc. If traffic matches multiple rules, the first rule to trigger will apply.

     • description: Rule description. This is an optional parameter.

     • override_variant_uuid: ID of the challenge option to show if the traffic matches the rule. If the parameter is not specified, the user will get the default challenge.

     • condition: One or more conditions for the incoming traffic. This is an optional parameter.

Result:

id: bpnd6cm6qpr5********
folder_id: b1g0ijbfaqsn********
cloud_id: b1gia87mbaom********
client_key: ysc1_2lla0Yn6dhlnEaTv2QNg2BhuA8Nqlyk4L7pZk3dz********
created_at: "2025-03-02T21:38:48.830498Z"
name: my-first-captcha
allowed_sites:
  - exmaple.ru
  - exmaple.kz
complexity: MEDIUM
style_json: '{"focus-color":"rgb(250, 192, 0)","base-background-color":"#fff"}'
turn_off_hostname_check: true
pre_check_type: CHECKBOX
challenge_type: IMAGE_TEXT
security_rules:
  - name: rule1
    priority: "11"
    description: My first security rule.
    condition:
      host:
        hosts:
          - exact_match: example.com
          - exact_match: example.net
    override_variant_uuid: variant-1
  - name: rule2
    priority: "12"
    condition:
      source_ip:
      geo_ip_match:
        locations:
          - ru
          - kz
    override_variant_uuid: variant-2
override_variants:
  - uuid: variant-1
    description: override variant 1
    complexity: EASY
    pre_check_type: CHECKBOX
    challenge_type: SILHOUETTES
  - uuid: variant-2
    description: override variant 2
    complexity: HARD
    pre_check_type: SLIDER
    challenge_type: KALEIDOSCOPE

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the relevant documentation on the Terraform website or its mirror.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

To create a CAPTCHA:

1. In the Terraform configuration file, describe the resources you want to create:

   resource "yandex_smartcaptcha_captcha" "<captcha_name>" {
     name                    = "<captcha_name>"
     turn_off_hostname_check = True
     style_json              = "<captcha_appearance>"
     complexity              = "<challenge_difficulty>"
     pre_check_type          = "<main_challenge_type>"
     challenge_type          = "<additional_challenge_type>"
   
     allowed_sites = [
       "<first_host>",
       "<second_host>"
     ]
   
     # First challenge variant
     override_variant {
       uuid        = "<variant_1_ID>"
       description = "<option_1_description>"
   
       complexity     = "<challenge_difficulty>"
       pre_check_type = "<main_challenge>"
       challenge_type = "<additional_challenge>"
     }
   
     # Second challenge variant 
     override_variant {
       uuid        = "<variant_2_ID"
       description = "<variant_2_description>"
   
       complexity     = "<challenge_difficulty>"
       pre_check_type = "<main_challenge>"
       challenge_type = "<additional_challenge>"
     }
   
     # First rule
     security_rule {
       name                  = "<rule_1_name>"
       priority              = <rule_1_priority>
       description           = "<rule_1_description>"
       override_variant_uuid = "<challenge_variant_ID>"
   
       condition {
         host {
           hosts {
             exact_match = "example.com"
           }
           hosts {
             exact_match = "example.net"
           }
         }
       }
     }
   
     # Second rule
     security_rule {
       name                  = "<rule_2_name>"
       priority              = <rule_2_priority>
       description           = "<rule_2_description>"
       override_variant_uuid = "<challenge_variant_ID>"
   
       condition {
         source_ip {
           geo_ip_match {
             locations = ["ru", "kz"]
           }
         }
       }
     }
   }
   

   Where:

   • name: CAPTCHA name.

   • turn_off_hostname_check: Disable domain check. This is an optional parameter.

   • style_json: Appearance of the challenge window and other elements, in JSON format. For more details, see the JSON generated using the management console. This is an optional parameter.

   • complexity: Difficulty level of the default challenge the user will get. The possible values are:

     • EASY: Simple challenge.
     • MEDIUM: Medium level challenge.
     • HARD: Difficult challenge.
     • FORCE_HARD: Difficult challenge with an additional question. The user is required to solve an additional challenge, regardless of the results of the main one.

     Note

     The feature of challenge options and show rules is at the Preview stage.

   • pre_check_type: Type of the default main challenge the user will get. The possible values are:

     • CHECKBOX: Checkbox.
     • SLIDER: Slider.

   • challenge_type: Type of the default additional challenge the user will get. The possible values are:

     • IMAGE_TEXT: Text recognition.
     • SILHOUETTES: Silhouettes.
     • KALEIDOSCOPE: Kaleidoscope.

   • allowed_sites: List of hosts as IP addresses or domain names without http/https or / at the end, e.g., example.com. The CAPTCHA will also be valid for all subdomains of the specified domain names. This is an optional parameter.

   • override_variant: Section containing the challenge option description. This is an optional parameter.

     • uuid: Unique ID of the challenge option.
     • description: Challenge option description. This is an optional parameter.
     • complexity: Difficulty level of the challenge the user will get.
     • pre_check_type: Type of the main challenge the user will get.
     • challenge_type: Type of the additional challenge the user will get.

   • security_rule: Section describing the rule for incoming traffic that will determine which CAPTCHA option to show. This is an optional parameter.

     • name: Rule name.

     • priority: Rule priority, from 1 to 999999.

       Rules are checked in ascending priority order, starting from 1, 2, etc. If traffic matches multiple rules, the first rule to trigger will apply.

     • description: Rule description. This is an optional parameter.

     • override_variant_uuid: ID of the challenge option to show if the traffic matches the rule. If the parameter is not specified, the user will get the default challenge.

     • condition: One or more conditions for the incoming traffic. This is an optional parameter.

   For more information about the yandex_smartcaptcha_captcha properties, see this Terraform provider article.

2. Create the resources:

   1. In the terminal, go to the directory where you edited the configuration file.

   2. Make sure the configuration file is correct using this command:

      terraform validate
      

      If the configuration is correct, you will get this message:

      Success! The configuration is valid.
      

   3. Run this command:

      terraform plan
      

      You will see a detailed list of resources. No changes will be made at this step. If the configuration contains any errors, Terraform will show them.

   4. Apply the changes:

      terraform apply
      

   5. Type yes and press Enter to confirm the changes.

   Terraform will create all the required resources. You can check the new resources using the management console or this CLI command:

   yc smartcaptcha captcha list
   

To create a CAPTCHA, use the create REST API method for the Captcha resource or the Captcha/Create gRPC API call.

1. Define the resource parameters in the configuration file:

   resource "yandex_smartcaptcha_captcha" "simple-captcha" {
     name           = "simple-captcha"
     complexity     = "HARD"
     pre_check_type = "SLIDER"
     challenge_type = "IMAGE_TEXT"
   }
   

   For more information about the yandex_smartcaptcha_captcha properties, see this Terraform provider article.

2. Create a CAPTCHA:

   1. In the terminal, go to the directory where you edited the configuration file.

   2. Make sure the configuration file is correct using this command:

      terraform validate
      

      If the configuration is correct, you will get this message:

      Success! The configuration is valid.
      

   3. Run this command:

      terraform plan
      

      You will see a detailed list of resources. No changes will be made at this step. If the configuration contains any errors, Terraform will show them.

   4. Apply the changes:

      terraform apply
      

   5. Type yes and press Enter to confirm the changes.

Use the create API method and provide the folder ID and CAPTCHA name in the request body:

{
  "folderId": "b1g0ijbfaqsn********",
  "name": "simple-captcha"
}

1. In the Terraform configuration file, describe the resource parameters, including the challenge options and rules for incoming traffic:

   resource "yandex_smartcaptcha_captcha" "advanced-captcha" {
     name                    = "advanced-captcha"
     turn_off_hostname_check = true
     style_json              = "${file("style.json")}"
     complexity              = "HARD"
     pre_check_type          = "SLIDER"
     challenge_type          = "IMAGE_TEXT"
   
     allowed_sites = [
       "example.ru",
       "example.kz"
     ]
   
     override_variant {
       uuid        = "variant-1"
       description = "Simple variant"
   
       complexity     = "EASY"
       pre_check_type = "CHECKBOX"
       challenge_type = "SILHOUETTES"
     }
   
     override_variant {
       uuid        = "variant-2"
       description = "Hard variant"
   
       complexity     = "HARD"
       pre_check_type = "SLIDER"
       challenge_type = "KALEIDOSCOPE"
     }
   
     security_rule {
       name                  = "rule-1"
       priority              = 11
       description           = "My first security rule"
       override_variant_uuid = "variant-1"
   
       condition {
         host {
           hosts {
             exact_match = "example.com"
           }
           hosts {
             exact_match = "example.net"
           }
         }
       }
     }
   
     security_rule {
       name                  = "rule-2"
       priority              = 12
       description           = "My second security rule"
       override_variant_uuid = "variant-2"
   
       condition {
         source_ip {
           geo_ip_match {
             locations = ["ru", "kz"]
           }
         }
       }
     }
   }
   

   For more information about the yandex_smartcaptcha_captcha properties, see this Terraform provider article.

2. Create a CAPTCHA:

   1. In the terminal, go to the directory where you edited the configuration file.

   2. Make sure the configuration file is correct using this command:

      terraform validate
      

      If the configuration is correct, you will get this message:

      Success! The configuration is valid.
      

   3. Run this command:

      terraform plan
      

      You will see a detailed list of resources. No changes will be made at this step. If the configuration contains any errors, Terraform will show them.

   4. Apply the changes:

      terraform apply
      

   5. Type yes and press Enter to confirm the changes.

Use the create API method, providing the following in the request body:

{
  "folderId": "b1g0ijbfaqsn********",
  "name": "advanced-captcha",
  "allowedSites": [
    "example.ru",
    "example.kz"
  ],
  "complexity": "HARD",
  "styleJson": "styleJson": "{\"text-color-primary\": \"#1e1f20\", \"base-background-color\": \"#c7d0d6\", \"popup-image-container-background-color\": \"#aab4ba\", \"base-checkbox-background-color\": \"#5a7080\", \"base-checkbox-background-color-checked\": \"#5a7080\", \"base-checkbox-border\": \"2px solid #5a7080\", \"base-checkbox-spin-color\": \"#5a7080\", \"popup-textinput-background-color\": \"#c7d0d6\", \"popup-action-button-background-color\": \"#5a7080\", \"popup-action-button-background-color-hover\": \"#485863\" }",
  "turnOffHostnameCheck": "TRUE",
  "preCheckType": "SLIDER",
  "challengeType": "IMAGE_TEXT",
  "securityRules": [
    {
      "name": "rule-1",
      "priority": "11",
      "description": "My first security rule",
      "condition": {
        "host": {
          "hosts": [
            { "exactMatch": "example.com" },
            { "exactMatch": "example.net" }
          ]
        }
      },
      "overrideVariantUuid": "variant-1"
    },
    {
      "name": "rule-2",
      "priority": "12",
      "description": "My second security rule",
      "condition": {
        "geoIpMatch": {
          "ipRangesMatch": {
            "locations": [
              "ru",
              "kz"
            ]
          }
        }
      },
      "overrideVariantUuid": "variant-2"
    }
  ],
  "overrideVariants": [
    {
      "uuid": "variant-1",
      "description": "Simple variant",
      "complexity": "EASY",
      "preCheckType": "CHECKBOX",
      "challengeType": "SILHOUETTES"
    },
    {
      "uuid": "variant-2",
      "description": "Hard variant",
      "complexity": "HARD",
      "preCheckType": "SLIDER",
      "challengeType": "SILHOUETTES"
    }
  ]
}