Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

웹페이지에 범용 키 설치

이 문서에서는 웹페이지에 범용 키를 설치하고 통합하는 방법을 설명합니다.

시작하기 전에

웹사이트에 범용 키 설치하기

범용 키를 설치하고 웹페이지를 보호하려면 AutoExecute 구성, 수동 JavaScript 설치를 사용하거나 동일한 범용 키를 사용하여 여러 엔드포인트에서 두 가지 방법을 함께 사용할 수 있습니다.

AutoExecute 구성 (권장): 구성된 URL 경로에 대한 비동기 네트워크 요청을 자동으로 가로채고 reCAPTCHA 토큰을 요청 헤더에 연결합니다.
수동 설치: 수동 grecaptcha.enterprise.execute() 호출 또는 HTML 버튼 속성을 사용합니다. 이 메서드는 단독으로 사용하거나 AutoExecute에서 지원하지 않는 네트워크 요청, 페이로드에 커스텀 토큰 배치가 필요한 요청 또는 AutoExecute로의 증분 마이그레이션 중에 AutoExecute와 함께 사용할 수 있습니다.

통합 방식에 따라 적절한 옵션을 선택합니다.

AutoExecute 구성

AutoExecute는 웹페이지에서 네트워크 요청을 가로채고 각 프런트엔드 작업에 대한 수동 grecaptcha.enterprise.execute() 호출을 제거하여 프런트엔드 JavaScript 통합을 간소화하는 데 도움이 될 수 있습니다.

AutoExecute는 Fetch API 또는 XMLHttpRequest로 시작된 비동기 네트워크 요청만 가로챕니다. 여기에는 이러한 API를 사용하는 AJAX와 같은 프레임워크의 요청이 포함됩니다.
페이지 로드 시 자동으로 로드되는 리소스에는 AutoExecute가 지원되지 않습니다. 대신 페이지에서 사용자 작업에 의해 트리거되는 네트워크 요청(예: 로그인 버튼)에 AutoExecute를 적용하세요.
Fraud Defense 질문으로 인해 네트워크 제한 시간이 발생하지 않도록 하려면 요청에 제한 시간을 직접 적용하세요. Fetch API에는 AbortSignal.timeout(n)를 사용하고 XMLHttpRequest에는 XMLHttpRequest.timeout 속성을 사용합니다.

웹페이지에 스크립트 태그 추가

웹페이지에서 Fraud Defense를 로드하려면 웹페이지의 <head></head> 요소 내에 범용 키가 있는 JavaScript API를 추가합니다.

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Fraud Defense는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 다음을 지정합니다.

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

지원되는 언어에 대한 자세한 내용은 Fraud Defense 언어 코드를 참조하세요.

보호되는 엔드포인트 구성

Fraud Defense 스크립트는 범용 키의 정책 구성에 정의된 네트워크 작업과 자동으로 통합됩니다. 이 섹션에서는 URL 경로 (path)와 작업 이름(action)의 매핑을 정의합니다.

Fraud Defense 스크립트가 매핑된 경로에 대한 비동기 네트워크 요청을 감지하면 요청을 가로채고 위험 평가를 트리거하며 원래 요청이 계속되기 전에 사용자에게 CAPTCHA 챌린지를 표시할 수 있습니다. 생성된 응답 토큰은 요청의 X-Recaptcha-Token 헤더에 자동으로 연결됩니다.

gcloud

범용 키의 현재 정책 구성을 검사하려면 gcloud alpha recaptcha policies describe 명령어를 사용합니다.

gcloud alpha recaptcha policies describe --key=KEY_ID

보호된 엔드포인트로 정책 구성을 업데이트하려면 보호된 경로와 작업을 정의하는 YAML 파일 (예: POLICY.yaml)을 만듭니다.

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

gcloud alpha recaptcha policies update 명령어를 사용하여 YAML 파일로 키 구성을 업데이트합니다.

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

REST API

REST API를 사용하여 보호된 엔드포인트를 정의하도록 정책 구성을 업데이트하려면 projects.keys.updatePolicy 메서드를 사용합니다.

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

PROJECT_ID: Google Cloud 프로젝트 ID
KEY_ID: 범용 키의 ID

HTTP 메서드 및 URL:

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

JSON 요청 본문:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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

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.protectedEndpointGroup"

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.protectedEndpointGroup" | Select-Object -Expand Content

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

범용 키당 최대 25개의 보호된 엔드포인트를 구성할 수 있습니다. 각 엔드포인트는 다음 요구사항을 충족해야 합니다.

action: 작업 이름은 1~100자(영문 기준)여야 하며 문자, 숫자, 슬래시(/), 밑줄(_)만 사용해야 합니다.
path (대소문자 구분): 경로는 다음 기준을 충족해야 합니다.
- 고유해야 하고 /로 시작해야 하며 연속 슬래시 (//) 없이 1~200자를 포함해야 합니다.
- 와일드 카드가 아닌 세그먼트를 하나 이상 포함합니다 (예: /, /*, /** 또는 /*/일 수 없음).
- 와일드 카드는 전체 세그먼트를 차지해야 합니다. *는 단일 세그먼트와 일치하고(예: /api/*/login 또는 /api/*는 유효하고 /api/login*는 잘못됨) **는 최종 세그먼트로만 여러 세그먼트와 일치합니다(예: /api/**는 유효하고 /api/**/login는 잘못됨).

서드 파티 요청: 페이지에서 실행되는 서드 파티 도구(예: 분석 또는 파트너 스크립트)가 보호된 엔드포인트와 일치하는 경로 (예: https://analytics.example.net/login가 /login와 일치)로 요청을 전송하는 경우 AutoExecute가 이를 가로챕니다. 이로 인해 추가 네트워크 지연 시간, 왜곡된 측정항목 또는 예기치 않은 보안문자 챌린지가 발생할 수 있습니다. 충돌을 방지하려면 보호된 경로가 고유한지 확인하거나 (예: /auth/v1/login) 경로 충돌이 발생하면 수동 설치를 사용하세요.
교차 도메인 API: 백엔드 API가 웹사이트와 다른 도메인에서 호스팅되는 경우 (예: examplecdn.net 및 www.example.com) AutoExecute는 추가 도메인 구성 없이 자동으로 작동합니다.

통합에 특정 대상 도메인과의 일치가 중요한 경우 기능 요청을 제출하세요.

백엔드에서 X-Recaptcha-Token 요청 헤더에서 응답 토큰을 가져오고 2분 이내에 평가를 만듭니다.

수동 설치

인증이 필요한 사용자 상호작용에 Fraud Defense 인증을 추가하는 것이 좋습니다. 예를 들어 양식의 제출 작업을 확인하려면 제출 작업에 Fraud Defense 인증을 추가해야 합니다.

Fraud Defense 인증을 추가할 위치에 따라 적절한 옵션을 선택합니다.

사용자 상호작용에 확인 추가
HTML 버튼에 Fraud Defense 추가

사용자 상호작용에 확인 추가

웹페이지에서 reCAPTCHA를 로드하려면 웹페이지의 <head></head> 요소 내에 범용 키가 있는 JavaScript API를 추가합니다.
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 다음을 지정합니다.

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

지원되는 언어에 대한 자세한 내용은 Fraud Defense 언어 코드를 참조하세요.

배지 위치를 지정하려면 스크립트 태그에서 badge=LOCATION를 쿼리 매개변수로 사용합니다. 예를 들면 https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft입니다. 기본적으로 위치가 bottomright로 설정됩니다. 다른 가능한 값은 inline과 bottomleft입니다.
사용자 상호작용에 Fraud Defense 인증을 추가하려면 다음을 수행합니다.
1. Fraud Defense 라이브러리가 로드된 후 grecaptcha.enterprise.execute()가 실행되도록 하려면 grecaptcha.enterprise.ready()를 사용합니다.
2. 범용 키로 보호하려는 각 상호작용에 대해 grecaptcha.enterprise.execute()를 호출합니다. action 매개변수에서 사용자 상호작용에 의미 있는 이름을 지정합니다. 자세한 내용은 작업을 참조하세요.
  
  팁: LOGIN, SIGNUP, PASSWORD_RESET, PURCHASE와 같은 민감한 작업에 execute 호출을 추가합니다.
  
  다음 예시에서는 로그인 작업에서 grecaptcha.enterprise.execute()를 호출하는 방법을 보여줍니다.
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>
```
토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 내에 평가를 만듭니다.

중요: 백엔드는 CreateAssessmentRequest에서 assessment.event.expected_action (또는 JSON의 expectedAction)를 지정해야 하며, 이는 execute() 호출에서 구성된 작업과 일치해야 합니다. 예를 들어 프런트엔드 작업을 LOGIN로 구성하는 경우 백엔드는 해당 요청에 대한 평가를 만들 때 expected_action를 LOGIN로 설정해야 합니다. 불일치가 있으면 공격자가 작업을 조작하려고 시도함을 나타냅니다.

HTML 버튼에 Fraud Defense 추가

웹페이지에서 reCAPTCHA를 로드하려면 웹페이지의 <head></head> 요소 내에 범용 키가 있는 JavaScript API를 추가합니다.
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 다음을 지정합니다.

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

지원되는 언어에 대한 자세한 내용은 Fraud Defense 언어 코드를 참조하세요.
HTML 버튼에 Fraud Defense를 추가하려면 다음을 수행합니다.
1. 토큰을 처리할 콜백 함수를 정의합니다.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
자세한 내용은 requestSubmit() 메서드를 참고하세요.
1. HTML 버튼에 속성을 추가합니다.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
배지 위치를 지정하려면 class="g-recaptcha"가 있는 요소에서 data-badge="LOCATION" 속성을 사용합니다. 기본적으로 위치가 bottomright로 설정됩니다. 다른 가능한 값은 inline과 bottomleft입니다.
1. 이 버튼을 사용하여 사이트의 양식을 제출하면 g-recaptcha-response POST 매개변수에 응답 토큰이 포함됩니다.
참고: g-recaptcha 버튼을 disabled로 설정하면 Fraud Defense가 로드될 때 이 버튼이 사용 설정됩니다.
토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 내에 평가를 만듭니다.

중요: 백엔드는 CreateAssessmentRequest에서 assessment.event.expected_action (또는 JSON의 expectedAction)를 지정해야 하며, 이는 버튼에 구성된 작업과 일치해야 합니다. 예를 들어 버튼 작업을 submit로 구성하는 경우 백엔드는 해당 요청에 대한 평가를 만들 때 expected_action를 submit로 설정해야 합니다. 불일치가 있으면 공격자가 작업을 조작하려고 시도함을 나타냅니다.

다음 단계

커스텀 규칙을 기반으로 보안문자 테스트를 트리거하려면 테스트 정책을 구성합니다.
reCAPTCHA 응답 토큰을 평가하려면 평가를 만듭니다.