도전과제 정책 구성

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

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

다음 권장 기능과 함께 챌린지 정책을 사용할 수 있습니다.

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

시작하기 전에

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

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

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

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

        Fraud Defense로 이동

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

    • 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 섹션을 사용하여 질문 정책을 구성할 수 있습니다.

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

콘솔

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

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

    Fraud Defense로 이동

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

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

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

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

  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 섹션의 전체 스키마는 인증 질문 정책 구성을 참고하세요.

다양한 사용 사례의 예시는 챌린지 규칙 구성 예시를 참조하세요.

테스트 정책 구성

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

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: {}

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

규칙 평가 순서

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

테스트 난이도

챌린지를 트리거할 때 난이도를 지정할 수 있습니다. 유효한 난이도 값의 전체 목록은 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 사용).
region_code string 요청 위치와 연결된 유니코드 CLDR 리전 코드 (ISO 3166-1 alpha-2 기반)(예: "US", "CA", "FR")입니다.
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 챌린지 정책에서는 이러한 변수를 사용하여 불리언 표현식을 생성할 수 있습니다. 예를 들어 score > 0.5, user_ip_address == "192.0.2.1", region_code == "US", user_asn == 12345는 불리언으로 평가되는 유효한 조건 표현식입니다. user_asn은 정수 유형이므로 ASN을 확인할 때 AS 프리픽스를 생략해야 합니다.

Fraud Defense 질문 정책 조건에서 사용할 수 있는 함수는 다음과 같습니다.

이름 서명 설명
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)

챌린지 규칙 구성 예시

이 섹션에는 유효한 챌린지 규칙 구성 예시가 포함되어 있습니다.

점수가 낮은 모든 요청에 대한 확인 요청

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

점수가 낮은 모든 요청에 대해 고마찰 챌린지 선택

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

점수가 낮은 특정 작업에 이의 제기

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 주소에 확인 질문 표시 안함

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 주소의 서브넷에 확인 질문 표시 안함

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

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

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 상담사에게 챌린지 표시 안함

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

복잡한 조건을 기반으로 챌린지 표시

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

다음 단계