도전과제 정책 구성

이 문서에서는 기존 Google Cloud Fraud Defense 통합으로 reCAPTCHA 테스트 정책을 구성하는 방법을 설명합니다.

reCAPTCHA 테스트 정책을 사용하면 맞춤 규칙에 따라 reCAPTCHA 테스트를 선택적으로 트리거할 수 있습니다. 이러한 규칙은 위험 점수, IP 주소, 사용자 에이전트, ASN 또는 확인된 봇 (AI 에이전트) ID를 기반으로 Fraud Defense 테스트를 표시할 시점을 결정합니다.

다음과 같은 권장 기능과 함께 reCAPTCHA 테스트 정책을 사용할 수 있습니다.

  • AutoExecute 구성: 클라이언트 애플리케이션의 JavaScript 통합을 간소화합니다.
  • 도전과제: 도전과제 규칙에 따라 필요한 경우 사용자 인증을 트리거합니다. Fraud Defense는 다음 reCAPTCHA 테스트 유형을 지원합니다.
    • 시각적 테스트: 사용자에게 프롬프트에 따라 이미지를 선택하도록 요청합니다. 기본적으로 reCAPTCHA 테스트 옵션을 선택한 상태로 규칙을 구성하면 시각적 테스트가 선택됩니다.
    • 오디오 테스트: 사용자에게 접근성 대안으로 음성 오디오 신호를 식별하도록 요청합니다.
    • QR 코드 도전과제: 사용자에게 휴대기기로 QR 코드를 스캔하여 도전과제를 해결하도록 요청합니다. 이 기능을 사용하려면 범용 키가 허용 목록에 있어야 합니다. 범용 키를 허용 목록에 추가하려면 fraud-defense@google.com으로 Fraud Defense팀에 문의하고 범용 키를 제공하세요.

시작하기 전에

  1. Google Cloud Fraud Defense를 위한 환경을 준비합니다.
  2. 프로젝트에 결제가 사용 설정되어 있는지 확인합니다 Google Cloud . 신용카드 또는 기존 Google Cloud 프로젝트 결제 ID를 사용하여 결제를 사용 설정할 수 있습니다. 결제와 관련해 도움이 필요하면 Cloud Billing 지원팀에 문의하세요.

  3. 프로젝트의 범용 키를 만들거나 식별합니다. 키를 만들려면 범용 키 만들기를 참조하세요. 또는 다음 단계 중 하나를 완료하여 기존 범용 키의 ID를 복사할 수 있습니다.

    • 콘솔에서 기존 키의 ID를 복사하려면 다음을 수행합니다. Google Cloud

      1. 콘솔에서 Google Cloud Google Cloud Fraud Defense 페이지로 이동합니다.

        Fraud Defense로 이동

      2. reCAPTCHA 키 목록에서 복사할 키를 찾아 클립보드에 복사 를 클릭합니다.

    • REST API를 사용하여 기존 키의 ID를 복사하려면 projects.keys.list 메서드를 호출합니다.

    • gcloud CLI를 사용하여 기존 키의 ID를 복사하려면 gcloud recaptcha keys list 명령어를 실행합니다.

  4. 보호할 사용자 작업 (예: login, signup 또는 password_reset)과 웹사이트에서 이러한 작업을 트리거하는 페이지를 식별하여 Fraud Defense 통합을 계획합니다. AutoExecute 구성을 사용하는 경우 이러한 작업이 protected_endpoint_group에 지정된 작업 이름과 일치하는지 확인합니다.

  5. 웹페이지에 Fraud Defense를 통합합니다. Fraud Defense AutoExecute 구성을 사용하는 것이 좋습니다. 일반적인 설정 안내는 웹사이트에 범용 키 설치를 참조하세요.

Fraud Defense 정책 구성 개요

Fraud Defense 정책 구성을 사용하면 Fraud Defense 보호의 동작을 맞춤설정할 수 있습니다. challenge_rule_groups 섹션을 사용하여 reCAPTCHA 테스트 정책을 구성할 수 있습니다.

콘솔, gcloud CLI 또는 reCAPTCHA Enterprise REST API를 사용하여 정책 구성을 보고 업데이트할 수 있습니다. Google Cloud

콘솔

콘솔에서 정책 구성을 보거나 업데이트하려면 다음을 수행하세요. Google Cloud

  1. 콘솔에서 Fraud Defense 페이지로 이동합니다. Google Cloud

    Fraud Defense로 이동

  2. 리소스 선택기에서 프로젝트가 선택되어 있는지 확인합니다.

  3. reCAPTCHA 키 표에서 reCAPTCHA 테스트 정책을 구성할 키의 이름을 클릭합니다.

  4. 키 세부정보 페이지에서 정책 탭으로 이동합니다.

  5. 규칙 그룹 섹션에서 reCAPTCHA 테스트 규칙 및 조건 표현식을 보거나 추가하거나 수정할 수 있습니다.

  6. 저장 을 클릭합니다.

gcloud

키의 정책 구성을 업데이트하려면 gcloud alpha recaptcha policies update 명령어를 실행합니다.

gcloud alpha recaptcha policies update --key=KEY_ID --policy=POLICY.yaml

키의 현재 정책 구성을 보려면 gcloud alpha recaptcha policies describe 명령어를 실행합니다.

gcloud alpha recaptcha policies describe --key=KEY_ID

REST API

키의 정책 구성을 업데이트하려면 projects.keys.updatePolicy 메서드를 호출합니다.

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

키의 현재 정책 구성을 보려면 projects.keys.getPolicy 메서드를 호출합니다.

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

정책 구성은 Google Cloud CLI의 경우 YAML 형식을 사용하고 REST API의 경우 JSON 형식을 사용합니다. challenge_rule_groups 섹션의 전체 스키마는 reCAPTCHA 테스트 정책 구성을 참조하세요.

다양한 사용 사례의 예시는 reCAPTCHA 테스트 규칙 구성 예시를 참조하세요.

reCAPTCHA 테스트 정책 구성

Fraud Defense 정책 구성의 challenge_rule_groups 섹션 내에서 reCAPTCHA 테스트 정책을 구성합니다. 도메인 정보를 포함하여 client_settings가 있는 정책이 이미 있는 경우 reCAPTCHA 테스트 정책 규칙을 포함하도록 정책을 업데이트할 수 있습니다.

challenge_rule_groups 섹션의 구조는 다음과 같습니다.

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

모든 reCAPTCHA 테스트 규칙에서 condition 필드는 선택사항입니다. condition이 지정되지 않거나 비어 있으면 규칙이 무조건 적용됩니다. 또한 challenge 및 no_challenge 필드는 상호 배타적이며 각 규칙에 정확히 하나 가 있어야 합니다.

규칙 평가 순서

규칙 그룹과 내부 규칙은 위에서 아래로 순차적으로 평가됩니다. 첫 번째 일치 규칙이 적용됩니다. 그룹과 규칙이 상호작용과 일치하지 않으면 평가 기본값이 표준 평가로 설정됩니다. reCAPTCHA 테스트는 표시되지 않지만 요청에 대한 위험 점수가 생성됩니다.

reCAPTCHA 테스트 난이도

reCAPTCHA 테스트를 트리거할 때 난이도를 지정할 수 있습니다. 유효한 난이도 값의 전체 목록은 ChallengeSecurityPreference API 참조를 확인하세요.

조건 구문

condition 필드는 Common Expression Language (CEL) 표현식으로 형식이 지정된 선택적 문자열입니다. condition이 지정되지 않거나 비어 있으면 규칙이 무조건 적용됩니다. CEL은 관계형 (<, <=, >, >=, ==, !=), 산술 (+, -, /, *, %), 논리 (!, &&, ||), 컨테이너 ([], in) 연산자를 비롯한 표준 C와 같은 연산자를 제공합니다. CEL은 일반적인 기본 데이터 유형 (bool, int, uint, double, string), 기본 컨테이너 유형 (lists, messages), 상수 (예: true, 1, 0.5, "hello", [1, 2, 3])를 지원합니다.

런타임 내에서 다음 Fraud Defense 변수에 액세스할 수 있습니다.

변수 유형 설명
score double Fraud Defense 봇 점수입니다.
user_ip_address string 요청을 하는 사용자의 IP 주소 (IPv4 또는 IPv6)입니다.
user_agent string 요청을 하는 사용자의 사용자 에이전트입니다.
user_asn int 요청을 하는 사용자의 자율 시스템 번호 (ASN)입니다. AS 프리픽스를 생략합니다 (예: AS12345 대신 12345 사용).
verified_bots list(Bot) Fraud Defense에서 식별한 확인된 자동 크롤러 또는 에이전트 (예: 검색엔진 색인 생성기, AI 검색 도우미, 파트너 콘텐츠 스크레이퍼) 목록입니다.

다음과 같은 추가 기본이 아닌 유형이 정의됩니다. 값의 전체 목록 은 봇을 참조하세요.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

가능한 name 값에 대한 자세한 내용은 Bot API 참조를 확인하세요. 유효한 bot_type enum 값에 대한 자세한 내용은 BotType API 참조를 확인하세요.

Fraud Defense reCAPTCHA 테스트 정책에서 이러한 변수를 사용하여 불리언 표현식을 생성할 수 있습니다. 예를 들어 score > 0.5, user_ip_address == "192.0.2.1", user_asn == 12345는 불리언으로 평가되는 유효한 조건 표현식입니다. user_asn은 정수 유형이므로 ASN을 확인할 때 AS 프리픽스를 생략해야 합니다.

Fraud Defense reCAPTCHA 테스트 정책 조건에서 사용할 수 있는 함수는 다음과 같습니다.

이름 서명 설명
contains string.contains(string) -> bool 문자열 피연산자에 하위 문자열이 포함되어 있는지 확인합니다.
startsWith string.startsWith(string) -> bool 문자열 피연산자가 지정된 프리픽스로 시작하는지 확인합니다.
endsWith string.endsWith(string) -> bool 문자열 피연산자가 지정된 서픽스로 끝나는지 확인합니다.
size size(string) -> int
size(list) -> int
string.size() -> int
list.size() -> int		 문자열의 크기 (코드 포인트 수) 또는 목록의 크기 (요소 수)를 반환합니다.

이해 함수는 CEL에 내장된 매크로 스타일입니다. 다음 이해를 사용할 수 있습니다.

이름 서명 설명 예
has has(message.field) -> bool 필드를 사용할 수 있는지 확인합니다. has(verified_bots[0].name)
all list(A).all(A, predicate(A) -> bool) -> bool 목록 e의 모든 요소 x가 조건자 p와 일치하는지 확인합니다. [1, 2, 3].all(x, x > 0)
exists list(A).exists(A, predicate(A) -> bool) -> bool 목록 e의 요소 x가 조건자 p와 일치하는지 확인합니다. [1, 2, 3].exists(i, i % 2 != 0)
exists_one list(A).exists_one(A, predicate(A)) -> bool 목록 e의 요소 x가 조건자 p와 정확히 일치하는지 확인합니다. [1, 2, 2].exists_one(i, i < 2)

reCAPTCHA 테스트 규칙 구성 예시

이 섹션에는 유효한 reCAPTCHA 테스트 규칙 구성 예시가 포함되어 있습니다.

점수가 낮은 모든 요청에 대해 reCAPTCHA 테스트

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

점수가 낮은 모든 요청에 대해 높은 마찰 reCAPTCHA 테스트 선택

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

점수가 낮은 특정 작업에 대해 reCAPTCHA 테스트

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

작업별로 다른 규칙 기준점 구성

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

허용 목록에 있는 IP 주소에 reCAPTCHA 테스트 표시 안함

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.001", "123.255.255.002"]'
        no_challenge: {}

참고: 이 규칙은 Fraud Defense IP 허용 목록 기능과 다릅니다.

IP 주소의 서브넷에 reCAPTCHA 테스트 표시 안함

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

특정 ASN의 요청에 reCAPTCHA 테스트 표시 안함

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

Google 에이전트에 reCAPTCHA 테스트 표시 안함

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

복잡한 조건을 기반으로 reCAPTCHA 테스트 표시

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

다음 단계