reCAPTCHA 익스프레스는 클라이언트 측에서 reCAPTCHA JavaScript 또는 모바일 SDK와 통합하는 것이 불가능한 경우(예: API 엔드포인트 보호) 애플리케이션 서버에서 설정할 수 있습니다.
reCAPTCHA 익스프레스는 클라이언트 측 통합이나 클라이언트 측 신호 없이 평가를 만들 수 있는 기능입니다. reCAPTCHA 익스프레스는 백엔드 신호만 사용하여 reCAPTCHA 위험 점수를 생성합니다. 이 위험 점수를 사용하여 요청을 제공할지, 테스트 페이지로 리디렉션할지, 나중에 분석할 수 있도록 로깅할지 결정할 수 있습니다.
시작하기 전에
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
Verify that billing is enabled for your Google Cloud project.
Enable the reCAPTCHA Enterprise API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.인증을 위한 API 키를 만듭니다.
Google Cloud 콘솔에서 사용자 인증 정보 페이지로 이동합니다.
사용자 인증 정보 만들기를 클릭한 후 API 키를 선택합니다.
나중에 사용할 수 있도록 API 키를 기록합니다.
reCAPTCHA 익스프레스 키 만들기
reCAPTCHA 익스프레스를 구현하려면 reCAPTCHA 익스프레스 키를 만듭니다.
In the Google Cloud console, activate Cloud Shell.
gcloud
reCAPTCHA 키를 만들려면 gcloud recaptcha keys create 명령어를 사용합니다.
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- INTEGRATION_TYPE: 통합 유형입니다.
score를 지정하세요. - DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
gcloud recaptcha keys create 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud recaptcha keys create \ --express \ --display-name=DISPLAY_NAME
Windows(PowerShell)
gcloud recaptcha keys create ` --express ` --display-name=DISPLAY_NAME
Windows(cmd.exe)
gcloud recaptcha keys create ^ --express ^ --display-name=DISPLAY_NAME
응답에 새로 생성된 reCAPTCHA 키가 포함됩니다.
REST
키 유형 및 통합 유형에 대한 API 참조 정보는 키 및 통합 유형을 참조하세요.요청 데이터를 사용하기 전에 다음을 바꿉니다.
- INTEGRATION_TYPE: 통합 유형입니다.
score를 지정하세요. - DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
- DEFAULT_SCORE_THRESHOLD: 정책 기반 챌린지 키의 경우 맞춤 점수 기준점이 정의되지 않은 경우 키의 범용 챌린지 기준점을 정의합니다. 이 기능은 미리보기로 제공됩니다.
- ACTION_SCORE_THRESHOLDS: 정책 기반 챌린지 키의 경우 작업과 0.0~1.0 사이의 해당 기준 점수를 지정합니다. 예를 들면
login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'입니다. 이 기능은 미리보기로 제공됩니다.
HTTP 메서드 및 URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
JSON 요청 본문:
{ "displayName": "DISPLAY_NAME", "expressSettings": {} }요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을
request.json파일에 저장하고 다음 명령어를 실행합니다.curl -X POST \
-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"PowerShell
요청 본문을
request.json파일에 저장하고 다음 명령어를 실행합니다.$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content다음과 비슷한 JSON 응답이 표시됩니다.
{ "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m", "displayName": "DISPLAY_NAME, "expressSettings": { } }- INTEGRATION_TYPE: 통합 유형입니다.
- API_KEY: 인증을 위해 만든 API 키
- EXPRESS_KEY: 애플리케이션을 위해 만든 reCAPTCHA 익스프레스 키
- USER_IP_ADDRESS: 이 이벤트와 관련된 사용자 기기의 요청에 있는 IP 주소
- HEADER_INFO: (선택사항) 클라이언트가 애플리케이션 서버로 전송한 HTTP 헤더 `[key:value]` 형식의 요청 헤더가 포함된 문자열 배열입니다. 예를 들면 `[key:value, key:value,...]`입니다. 필요한 순서대로 최대한 많은 헤더를 공유하는 것이 좋습니다. 같은 세션의 모든 요청에서 헤더 순서가 일관적인지 확인합니다.
- JA3_FINGERPRINT: 선택사항. JA3는 TLS 클라이언트 Hello 패킷의 특정 필드에 대한 MD5 지문. 자세한 내용은 JA3 - SSL/TLS 클라이언트 프로파일링 방법을 참조하세요.
- URI_NAME: (선택사항) 사용자가 액세스하는 URI
- USER_AGENT: (선택사항) 이 이벤트와 관련된 사용자 기기의 요청에 있는 사용자 에이전트
- ACCOUNT_ID: (선택사항) 해싱된 계정 이름과 같이 사용자 계정의 고유한 영구 식별자입니다.
나중에 사용할 수 있도록 익스프레스 키를 기록합니다.
평가 작성
애플리케이션 서버에서 reCAPTCHA에 요청하려면 projects.assessments.create 메서드를 사용하여 평가를 작성합니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
HTTP 메서드 및 URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
JSON 요청 본문:
{
"event": {
"siteKey": "EXPRESS_KEY",
"express": true,
"userIpAddress": "USER_IP_ADDRESS",
"headers": ["HEADER_INFO"],
"ja3": "JA3_FINGERPRINT",
"requestedUri": "URI_NAME",
"userAgent": "USER_AGENT",
"user_info": {
"account_id": "ACCOUNT_ID"
}
}
}
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"
PowerShell
요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.
$headers = @{ }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content다음과 비슷한 JSON 응답이 표시됩니다.
{
"name": "projects/123456789/assessments/abcdef1234000000",
"event": {
"token": "",
"siteKey": "6L...",
"userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
"userIpAddress": "1.2.3.4",
"express": true,
"requestedUri": "https://example.com/",
"user_info": {
"account_id": "123456789"
},
"headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
},
"riskAnalysis": {
"score": 0.7,
"reasons": []
}
}
점수 해석
reCAPTCHA 익스프레스는 0.3 및 0.7 등 두 가지 점수만 반환합니다.
0.3은 사용자 상호작용이 더 위험하고 허위일 가능성이 높음을 나타내고 0.7은 사용자 상호작용이 위험도가 낮고 적법할 가능성이 높음을 나타냅니다.
신호가 부족하면 reCAPTCHA 익스프레스는 기본적으로 0.7을 반환합니다.