애플리케이션 서버에서 reCAPTCHA 익스프레스 설정

이 문서에서는 reCAPTCHA JavaScript 또는 모바일 SDK의 통합이 불가능한 환경(예: API 엔드포인트 보호)에서 애플리케이션 서버에 reCAPTCHA 익스프레스를 설정하는 방법을 보여줍니다.

reCAPTCHA 익스프레스는 클라이언트 측 기능 없이 평가를 생성할 수 있는 기능입니다. reCAPTCHA 익스프레스는 백엔드 신호만 사용하여 reCAPTCHA 위험 점수를 생성합니다. 이 위험 점수를 사용하여 요청을 제공할지, 테스트 페이지로 리디렉션할지, 나중에 분석할 수 있도록 로깅할지 결정할 수 있습니다.

시작하기 전에

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector
나중에 사용할 수 있도록 Google Cloud 프로젝트 ID를 기록합니다.
Make sure that billing is enabled for your Google Cloud project.
Enable the reCAPTCHA Enterprise API.
Enable the API
인증을 위한 API 키를 만듭니다.
1. Google Cloud 콘솔에서 사용자 인증 정보 페이지로 이동합니다.
  
  사용자 인증 정보로 이동
2. 사용자 인증 정보 만들기를 클릭한 후 API 키를 선택합니다.
3. 나중에 사용할 수 있도록 API 키를 기록합니다.

reCAPTCHA 익스프레스 키 만들기

reCAPTCHA 익스프레스를 구현하려면 reCAPTCHA 익스프레스 키를 만듭니다.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
gcloud

reCAPTCHA 키를 만들려면 gcloud recaptcha keys create 명령어를 사용합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- 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 참조 정보는 키 및 통합 유형을 참조하세요.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
HTTP 메서드 및 URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys
JSON 요청 본문:
{ "displayName": "DISPLAY_NAME", "expressSettings": {} }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl

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

요청 본문을 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

참고: 다음 명령어는 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 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": { } }

나중에 사용할 수 있도록 익스프레스 키를 기록합니다.

평가 작성

애플리케이션 서버에서 reCAPTCHA에 요청하려면 projects.assessments.create 메서드를 사용하여 평가를 작성합니다.

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

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: (선택사항) 해싱된 계정 이름과 같이 사용자 계정의 고유하고 영구적인 식별자입니다.

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/",
    "firewallPolicyEvaluation": false,
    "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을 반환합니다.

애플리케이션 서버에서 reCAPTCHA 익스프레스 설정

시작하기 전에

reCAPTCHA 익스프레스 키 만들기

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

curl

PowerShell

평가 작성

curl

PowerShell

점수 해석

다음 단계