기존 SiteVerify로 사용자 응답 토큰 확인

이 페이지에서는 기존 SiteVerify API 엔드포인트 (https://www.google.com/recaptcha/api/siteverify)를 사용하여 애플리케이션 백엔드에서 reCAPTCHA 테스트에 대한 사용자 응답을 인증하는 방법을 설명합니다. CreateAssessment를 사용할 수 없는 기존 통합 또는 서드 파티 플러그인을 유지관리하는 경우에만 이 엔드포인트를 사용하세요.

시작하기 전에

SiteVerify 엔드포인트를 호출하려면 키의 기존 보안 비밀 키가 필요합니다. Google Cloud 콘솔에서 비밀 키를 찾는 방법은 Google Cloud 콘솔에서 비밀 키 가져오기를 참고하세요. 백엔드 서버에서 보안 키를 안전하게 유지하고 클라이언트 측 코드에 노출하지 마세요.

사용자 응답 토큰 검색

기존 웹 통합은 엔터프라이즈가 아닌 JavaScript API(https://www.google.com/recaptcha/api.js)를 로드하며, 이 API는 grecaptcha.enterprise 대신 grecaptcha 객체에 메서드를 제공합니다. 다음 방법 중 하나로 프런트엔드에서 사용자의 응답 토큰을 가져올 수 있습니다.

  • 사용자가 사이트에서 양식을 제출할 때 g-recaptcha-response POST 매개변수에서 가져옵니다.
  • 사용자가 reCAPTCHA v2 테스트를 완료한 후 grecaptcha.getResponse(opt_widget_id)를 호출합니다. 이 메서드는 응답 토큰을 문자열로 반환하거나 챌린지가 완료되지 않은 경우 빈 문자열을 반환합니다. 선택사항인 opt_widget_id 매개변수는 grecaptcha.render()에서 반환된 위젯 ID를 지정합니다. 생략하면 생성된 첫 번째 위젯이 기본값으로 사용됩니다.
  • 사용자가 챌린지를 완료할 때 콜백 함수에 전달되는 문자열 인수로 사용합니다. g-recaptcha HTML 요소의 data-callback 속성이나 grecaptcha.render(container, parameters) 메서드의 callback 매개변수에 콜백 함수 이름을 지정하는 경우에 해당합니다.
  • 점수 기반 (v3) 키의 경우 grecaptcha.execute(site_key, {action: action_name})에서 반환된 Promise의 확인된 값에서 가져옵니다.

기존 grecaptcha 메서드 (render, getResponse, execute, ready, reset)와 g-recaptcha 태그 속성은 grecaptcha.enterprise과 동일한 매개변수를 사용합니다. 매개변수 세부정보는 reCAPTCHA용 JavaScript API 참조를 참고하세요.

업데이트된 reCAPTCHA JavaScript API로 마이그레이션하려면 reCAPTCHA JavaScript API 마이그레이션을 참고하세요.

토큰 제한

각 reCAPTCHA 사용자 응답 토큰은 2분 동안 유효하며, 재생 공격을 방지하기 위해 각 토큰을 한 번만 인증할 수 있습니다. 응답 토큰을 수신한 후 2분 이내에 reCAPTCHA로 인증합니다. 새 토큰이 필요한 경우 reCAPTCHA 인증을 다시 실행하세요.

API 요청

다음 엔드포인트와 메서드로 요청을 전송합니다.

  • URL: https://www.google.com/recaptcha/api/siteverify (또는 www.google.com에 액세스할 수 없는 경우 https://www.recaptcha.net/recaptcha/api/siteverify, 전역적으로 reCAPTCHA 사용 참고)
  • 메서드: POST

요청에 다음 POST 매개변수를 포함합니다.

POST 매개변수 설명
secret 필수 항목입니다. 사이트와 reCAPTCHA 간의 공유 보안 비밀 키입니다.
response 필수 항목입니다. 사이트의 reCAPTCHA 클라이언트 측 통합에서 제공하는 사용자 응답 토큰입니다.
remoteip (선택사항) 사용자의 IP 주소입니다.

API 응답

SiteVerify 엔드포인트는 JSON 객체를 반환합니다.

웹 통합 (점수 기반 v3, 체크박스 v2 또는 보이지 않는 v2 키)의 경우 응답의 형식은 다음과 같습니다.

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

오류 코드 참조

다음 표에서는 error-codes 배열에 표시될 수 있는 오류 코드를 설명합니다.

오류 코드 설명
missing-input-secret secret 매개변수가 누락되었습니다.
invalid-input-secret secret 매개변수가 잘못되었거나 형식이 잘못되었습니다.
missing-input-response response 매개변수가 누락되었습니다.
invalid-input-response response 매개변수가 잘못되었거나 형식이 잘못되었습니다.
bad-request 요청이 유효하지 않거나 형식이 잘못되었습니다.
timeout-or-duplicate 응답이 만료되었거나 이미 사용되었기 때문에 더 이상 유효하지 않습니다.

다음 단계