범용 키로 정책 엔진 설정

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '현재 상태 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 범용 키를 사용하여 웹사이트에서 정책 엔진을 구성하는 방법을 설명합니다. 유니버설 키는 정책 엔진 내에서 규칙 생성을 지원하는 새로운 Google Cloud 사기 방지 키입니다.

정책 엔진을 사용하면 Fraud Defense에서 구성한 맞춤 정책 규칙에 따라 보안문자 테스트를 결정론적으로 트리거할 수 있습니다. 이러한 규칙은 위험 점수, IP 주소, 사용자 에이전트, ASN 또는 인증된 봇 (AI 에이전트) ID를 기반으로 사기 방지 챌린지를 표시할 시기를 결정할 수 있습니다.

Fraud Defense 정책 엔진 구성은 두 가지 주요 기능을 제공합니다.

• AutoExecute 통합 (protected_endpoint_group): 전송되는 비동기 네트워크 요청을 자동으로 검사하고 reCAPTCHA 토큰을 연결하여 프런트엔드 JavaScript 통합을 간소화하므로 프런트엔드에 스크립트 태그만 있으면 됩니다.
• 챌린지 정책 (challenge_rule_groups): 다양한 사용자 작업에 걸쳐 챌린지를 표시할지 여부를 결정하고 맞춤 CEL 기반 규칙을 사용하여 연결된 챌린지 난이도 (USABILITY, BALANCE, SECURITY)를 구성합니다.

시작하기 전에

1. reCAPTCHA 환경을 준비합니다.

2. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

   Fraud Defense를 사용하려면 정책 엔진을 사용하기 위해 프로젝트에 결제를 연결하고 사용 설정해야 합니다. 신용카드 또는 기존 Google Cloud 프로젝트 결제 ID를 사용하여 결제를 사용 설정할 수 있습니다. 결제와 관련해 도움이 필요하면 Cloud Billing 지원팀에 문의하세요.

범용 키 만들기

선호하는 인터페이스에 따라 적절한 옵션을 선택하여 범용 키를 만듭니다.

콘솔

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

   reCAPTCHA로 이동

2. 페이지 상단의 리소스 선택기에 프로젝트 이름이 표시되는지 확인합니다.

   프로젝트 이름이 표시되지 않으면 리소스 선택기를 클릭한 다음 프로젝트를 선택합니다.

3. 키 탭을 선택합니다.
4. 키 만들기를 클릭합니다.
5. 표시 이름 필드에 키의 표시 이름을 입력합니다.
6. 애플리케이션 유형으로 유니버설을 선택합니다.
7. 키 만들기를 클릭합니다.

reCAPTCHA 키 페이지에 새로 생성된 키가 나열됩니다.

gcloud

Google Cloud CLI를 사용하여 범용 키를 만들려면 --universal 플래그와 함께 gcloud recaptcha keys create 명령어를 사용합니다.

gcloud recaptcha keys create --universal --display-name=DISPLAY_NAME

응답에 새로 생성된 reCAPTCHA 유니버설 키가 포함됩니다.

REST API

REST API를 사용하여 범용 키를 만들려면 projects.keys.create 메서드를 사용하고 universalSettings를 지정합니다.

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

{
  "displayName": "DISPLAY_NAME",
  "universalSettings": {}
}

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID
• DISPLAY_NAME: 키의 표시 이름입니다(일반적으로 웹사이트 이름).

응답에 새로 생성된 reCAPTCHA 유니버설 키가 포함됩니다.

정책 엔진의 도메인 구성

참고: 웹사이트의 경우 reCAPTCHA 키는 지정한 도메인과 하위 도메인에 고유합니다. 여러 도메인에서 웹사이트를 제공할 경우 도메인을 2개 이상 지정할 수 있습니다. 도메인 (예: examplepetstore.com)을 지정할 때는 하위 도메인 (예: subdomain.examplepetstore.com)을 지정할 필요가 없습니다.

선호하는 인터페이스에 따라 적절한 옵션을 선택하여 범용 키에 허용된 도메인을 구성합니다.

콘솔

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

   Fraud Defense로 이동

2. 페이지 상단의 리소스 선택기에 프로젝트 이름이 표시되는지 확인합니다.

   프로젝트 이름이 표시되지 않으면 리소스 선택기를 클릭한 후 프로젝트를 선택합니다.

3. reCAPTCHA 키 탭을 클릭합니다.

4. 구성할 범용 키를 식별하고 키를 클릭합니다.

5. 키 세부정보 페이지에서 키 수정을 클릭합니다.

6. 키 사용 설정 섹션을 찾습니다.

   도메인과 하위 도메인의 reCAPTCHA 키를 보호하려면 도메인 확인 사용 중지 전환이 사용 중지되어 있는지 확인합니다.

   도메인 확인을 사용 중지하면 사이트에 제한이 없으므로 reCAPTCHA 키를 누구나 액세스하고 사용할 수 있어서 보안 위험이 발생합니다.

   웹사이트의 도메인 이름을 입력합니다.

   1. 도메인 목록 섹션에서 도메인 추가를 클릭합니다.
   2. 도메인 필드에 도메인 이름을 입력합니다.
   3. 선택사항: 도메인을 더 추가하려면 도메인 추가를 클릭하고 도메인 필드에 다른 도메인의 이름을 입력합니다. 도메인을 최대 250개까지 추가할 수 있습니다.

7. 변경사항 저장을 클릭합니다.

참고: 250개가 넘는 도메인에서 정책을 사용하려면 도메인 확인 사용 중지 전환 버튼을 클릭합니다. 도메인 확인이 사용 중지되면 Fraud Defense에서 도메인 목록을 무시하며, 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

gcloud

Google Cloud CLI를 사용하여 범용 키의 허용된 도메인을 업데이트하려면 gcloud alpha recaptcha policies update 명령어를 사용하고 정책 구성 파일 (예: POLICY.yaml)에 도메인을 지정합니다.

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

참고: gcloud alpha recaptcha policies update 명령어는 전체 정책을 업데이트합니다. 기존 protected_endpoint_group 또는 challenge_rule_groups가 삭제되지 않도록 POLICY.yaml 파일에 포함해야 합니다.

POLICY.yaml 파일은 clientSettings 아래에 허용된 도메인을 지정해야 합니다.

clientSettings:
  allowedDomains:
    - DOMAIN_NAME_1
    - DOMAIN_NAME_2

또는 모든 도메인을 허용하고 도메인 확인을 사용 중지하려면 POLICY.yaml 파일에서 allowAllDomains를 true로 설정하세요.

clientSettings:
  allowAllDomains: true

다음을 바꿉니다.

• KEY_ID: 범용 키의 ID 또는 전체 리소스 이름
• DOMAIN_NAME_1, DOMAIN_NAME_2: 키를 사용할 수 있는 웹사이트의 도메인 이름

참고: allowAllDomains가 true로 설정되면 사기 방어에서 도메인 목록을 무시하므로 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

REST API

REST API를 사용하여 범용 키의 허용된 도메인을 업데이트하려면 projects.keys.updatePolicy 메서드를 사용하세요.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID
• KEY_ID: 범용 키의 ID
• DOMAIN_NAME_1, DOMAIN_NAME_2: 키를 사용할 수 있는 웹사이트의 도메인 이름

HTTP 메서드 및 URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains

JSON 요청 본문:

{
"clientSettings": {
  "allowedDomains": [
    "DOMAIN_NAME_1",
    "DOMAIN_NAME_2"
  ],
  "allowAllDomains": false
}
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.allowedDomains,clientSettings.allowAllDomains" | Select-Object -Expand Content

요청이 성공하면 업데이트된 정책 구성이 반환됩니다.

참고: 250개가 넘는 도메인에서 정책을 사용하려면 요청 본문에서 allowAllDomains를 true로 설정하세요. allowAllDomains이 true로 설정된 경우 Fraud Defense에서 도메인 목록을 무시하며, 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

다음 단계

• 웹페이지에 범용 키 설치