웹페이지에 범용 키 설치

Fraud Defense 범용 키는 자동화된 봇 공격, 사용자 인증 정보 악용, 사기로부터 웹 애플리케이션과 API 엔드포인트를 보호하는 데 도움이 됩니다. 범용 키를 사용하면 자동 네트워크 요청 가로채기(AutoExecute), 수동 JavaScript 실행 또는 두 방법의 조합을 통해 웹사이트 전반에 보호 기능을 배포할 수 있습니다.

시작하기 전에

  1. Google Cloud Fraud Defense를 위한 환경을 준비합니다.

  2. 범용 키를 만듭니다.

  3. 범용 키의 도메인을 구성합니다.

  4. Google Cloud 콘솔에서 보호된 엔드포인트의 상태 열을 보려면 Cloud Monitoring monitoring.timeSeries.list 권한이 있는지 확인합니다. 이 권한은 사전 정의된 Fraud Defense 역할인 reCAPTCHA Enterprise 관리자, reCAPTCHA Enterprise 편집자, reCAPTCHA Enterprise 뷰어에 포함되어 있습니다.

웹사이트에 범용 키 설치

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

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

AutoExecute 구성

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

AutoExecute 작동 방식

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

지원되는 네트워크 API

AutoExecute는 다음 API(이 API를 사용하는 AJAX와 같은 프레임워크 포함)에서 시작된 비동기 네트워크 요청만 가로챕니다.

API 이름 제한 시간 구성 구현 예시
Fetch API AbortSignal 컨트롤러를 사용하여 제한 시간을 설정합니다. AbortSignal.timeout(n)
XMLHttpRequest 네이티브 .timeout 속성을 사용하여 제한 시간을 설정합니다. xhr.timeout = n

통합 권장사항

  • 사용자가 트리거하는 작업만: AutoExecute는 페이지 로드 중에 자동으로 로드되는 리소스를 지원하지 않습니다. 통합 실패를 방지하려면 명시적인 사용자 상호작용(예: 로그인 또는 제출 버튼 클릭)에 의해 트리거된 요청에만 AutoExecute를 적용하세요.
  • 지연 시간 초과 방지: Fraud Defense 질문 흐름으로 인해 네트워크 지연이 발생할 수 있습니다. 클라이언트 측 제한 시간을 방지하려면 항상 표에 나열된 메커니즘을 사용하여 명시적인 요청 제한 시간을 직접 구성하세요.
  • 민감한 경로만 보호: 민감한 경로에만 protectedEndpoints를 지정하고 action 매개변수에서 사용자 상호작용에 의미 있는 이름을 사용합니다. 모든 백엔드 요청에서 Fraud Defense를 트리거하면 성능에 부정적인 영향을 미칠 수 있으므로 모든 엔드포인트를 보호하지 마세요. 자세한 내용은 작업을 참조하세요.

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

웹페이지에서 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 언어 코드를 참조하세요.

보호되는 엔드포인트 구성

범용 키의 보호된 엔드포인트를 구성하려면 탭을 선택하세요.

콘솔

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

    Fraud Defense로 이동

  2. 콘솔 툴바에서 프로젝트가 리소스 선택기에 표시되는지 확인합니다. 그렇지 않으면 리소스 선택기를 클릭한 후 프로젝트를 선택합니다.

  3. 키 탭을 선택합니다.

    키 탭에는 카드와 테이블이라는 두 가지 뷰가 있습니다. 프로젝트에 키가 많은 경우 테이블 뷰만 사용할 수 있습니다.

  4. reCAPTCHA 키 섹션에서 구성하려는 범용 키를 찾습니다.

    • 카드 보기에서 키 카드의 키 세부정보를 클릭합니다.
    • 테이블 뷰에서 키 이름을 클릭합니다.
  5. 키 세부정보 페이지에서 통합 탭을 클릭합니다.

  6. 웹사이트에 reCAPTCHA 추가 단계에서 AutoExecute(권장) 탭을 선택합니다.

    선택사항: 특정 엔드포인트를 수동으로 보호하려면 수동 탭을 클릭하여 grecaptcha.enterprise.execute() 코드 스니펫을 확인합니다.

  7. 보호되는 엔드포인트 섹션에서 엔드포인트 추가를 클릭하여 보호할 각 엔드포인트를 구성합니다.

    1. 작업 필드에 사용자 상호작용의 이름을 입력합니다. 예를 들면 login, register 또는 add_to_cart입니다. 자세한 내용은 작업을 참조하세요.
    2. 경로 필드에 가로챌 고유 URL 경로 또는 glob 패턴을 입력합니다. 예를 들면 /login_api, /register_api, /cart_api/add/*입니다.
    3. 선택사항: 다른 엔드포인트를 추가하려면 엔드포인트 추가를 클릭합니다.
  8. 저장을 클릭하여 보호된 엔드포인트를 저장합니다.

구성을 저장하면 보호된 엔드포인트 테이블의 상태 열에 지난 24시간 동안 각 작업에 대해 Fraud Defense에서 트래픽을 수신했는지 여부가 표시됩니다. 엔드포인트가 처음 트래픽을 수신한 후 트래픽 상태가 업데이트되는 데 10분이 걸릴 수 있습니다.

gcloud

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

gcloud alpha recaptcha policies describe --key=KEY_ID

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

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - 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

JSON 요청 본문:

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

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

성공하면 요청에서 업데이트된 정책 구성을 반환합니다.

보호되는 엔드포인트 문법 및 한도

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

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

경로 일치 동작

AutoExecute는 보호된 엔드포인트를 위에서 아래로 순차적으로 URL 경로만에 대해 평가합니다. 대상 도메인, 스키마, 쿼리 매개변수는 무시됩니다. 이 동작은 다음과 같은 실질적인 의미를 갖습니다.

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

특정 도착 페이지 도메인과 일치하는 것이 통합에 중요한 경우 기능 요청을 제출하세요.

백엔드에서 토큰 확인

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

수동 설치

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

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

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

  1. 웹페이지에서 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입니다.

  2. 사용자 상호작용에 Fraud Defense 인증을 추가하려면 다음을 수행합니다.

    1. Fraud Defense 라이브러리가 로드된 후 grecaptcha.enterprise.execute()가 실행되도록 하려면 grecaptcha.enterprise.ready()를 사용합니다.
    2. 범용 키로 보호하려는 각 상호작용에 대해 grecaptcha.enterprise.execute()를 호출합니다. action 매개변수에서 사용자 상호작용에 의미 있는 이름을 지정합니다. 자세한 내용은 작업을 참조하세요.

      다음 예시에서는 로그인 작업에서 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>
      
  3. 토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 내에 평가를 만듭니다.

HTML 버튼에 Fraud Defense 추가

  1. 웹페이지에서 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 언어 코드를 참조하세요.

  2. HTML 버튼에 Fraud Defense를 추가하려면 다음을 수행합니다.

    1. 토큰을 처리할 콜백 함수를 정의합니다.

      <script>
        function onSubmit(token) {
          document.getElementById("demo-form").submit();
        }
        // Use `requestSubmit()` for extra features like browser input
        // validation.
      </script>
      

      자세한 내용은 requestSubmit() 메서드를 참조하세요.

    2. 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입니다.

    3. 이 버튼을 사용하여 사이트의 양식을 제출하면 g-recaptcha-response POST 매개변수에 응답 토큰이 포함됩니다.

  3. 토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 내에 평가를 만듭니다.

다음 단계