이 문서에서는 범용 키를 설치하고 웹페이지와 통합하는 방법을 설명합니다.
시작하기 전에
웹사이트에 범용 키 설치
범용 키를 설치하고 웹페이지를 보호하려면 Google Cloud Fraud Defense AutoExecute 구성 또는 표준 JavaScript 설치를 선택하세요.
AutoExecute 구성
Fraud Defense AutoExecute는 웹페이지에서 네트워크 요청을 가로채고 각 프런트엔드 작업에 대해 grecaptcha.enterprise.execute()를 수동으로 호출할 필요가 없도록 하여 프런트엔드 JavaScript 통합을 간소화할 수 있습니다.
AbortSignal.timeout(n)을 사용하고
XMLHttpRequest에는 XMLHttpRequest.timeout 속성을 사용합니다
XMLHttpRequest.웹페이지에 스크립트 태그 추가
웹페이지에서 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 언어 코드를 참조하세요.
보호된 엔드포인트 구성
Fraud Defense 스크립트는 범용 키의 정책 구성에 정의된 네트워크 작업과 자동으로 통합됩니다.
이 섹션에서는 URL 경로 (path)를 작업 이름(action)에 매핑하는 방법을 정의합니다.
Fraud Defense 스크립트가 매핑된 경로에 대한 비동기 네트워크 요청을 감지하면 요청을 가로채고 위험 평가를 트리거하며 원래 요청이 계속되기 전에 사용자에게 보안문자 테스트를 표시할 수 있습니다. 생성된 응답 토큰은 요청의 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: 프로젝트 ID Google Cloud
- 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"
}
]
}
}
}
요청을 보내려면 다음 옵션 중 하나를 펼칩니다.
성공하면 요청에서 업데이트된 정책 구성을 반환합니다.path 매개변수는 다음 규칙으로 glob 패턴을 지원합니다.
/로 시작해야 하며 비어 있을 수 없습니다.- 백엔드에 대한 모든 요청에서 Fraud Defense를 트리거하면 성능에 부정적인 영향을 미칠 수 있으므로 독립형
/*또는/**일 수 없습니다. - 와일드 카드
*(단일 경로 세그먼트와 일치) 및**(여러 경로 세그먼트와 일치)는 경로 세그먼트 전체를 차지해야 합니다 (예:/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 인증을 추가할 위치에 따라 적절한 옵션을 선택하세요.
사용자 상호작용에 확인 추가
웹페이지에서 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 인증을 추가하려면 다음을 수행합니다.
- Fraud Defense 라이브러리가 로드된 후
grecaptcha.enterprise.execute()가 실행되도록 하려면grecaptcha.enterprise.ready()를 사용합니다. 범용 키로 보호하려는 각 상호작용에 대해
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>s
- Fraud Defense 라이브러리가 로드된 후
토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 이내에 평가를 만듭니다.
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를 추가하려면 다음을 수행합니다.
- 토큰을 처리할 콜백 함수를 정의합니다.
<script> function onSubmit(token) { document.getElementById("demo-form").submit(); } // Use `requestSubmit()` for extra features like browser input // validation. </script>자세한 내용은 requestSubmit() 메서드를 참조하세요.
- HTML 버튼에 속성을 추가합니다.
<button class="g-recaptcha" data-sitekey="KEY_ID" data-callback="onSubmit" data-action="submit">Submit</button>배지 위치를 지정하려면
data-badge="LOCATION"속성을 요소에서 사용합니다.class="g-recaptcha"기본적으로 위치가bottomright로 설정됩니다. 가능한 다른 값은inline및bottomleft입니다.- 이 버튼을 사용하여 사이트의 양식을 제출하면
g-recaptcha-responsePOST 매개변수에 응답 토큰이 포함됩니다.
토큰이 생성되면 reCAPTCHA 토큰을 백엔드로 보내고 2분 이내에 평가를 만듭니다.
다음 단계
커스텀 규칙에 따라 보안문자 테스트를 트리거하려면 테스트 정책을 구성합니다.
reCAPTCHA 응답 토큰을 평가하려면 평가를 만듭니다.