웹사이트에 점수 기반 키 설치

이 페이지에서는 웹사이트에 챌린지 없이 점수 기반 키를 설치하는 방법을 설명합니다. 점수 기반 키를 사용하면 사용자가 CAPTCHA 챌린지에 답하지 않고도 사이트 전체에서 reCAPTCHA를 포함할 수 있습니다.

점수 기반 키가 설치되면 reCAPTCHA는 최종 사용자가 상호작용을 트리거할 때 암호화된 응답인 reCAPTCHA 응답 토큰(토큰이라고도 함)을 전송합니다. 토큰이 생성된 후 2분 이내에 평가를 만들어 각 요청에 대한 점수를 받아야 합니다. 점수를 기준으로 사용자 상호작용의 위험도를 이해하고 적절한 응답을 구성할 수 있습니다. 또한 점수 기반 키는 새로운 공격이나 대상에 대한 조기 경고를 위해 봇 활동 원격 분석 정보를 수집할 수 있습니다.

reCAPTCHA의 위험 모델을 개선하려면 사이트의 모든 페이지에 reCAPTCHA를 포함하는 것이 좋습니다. 실제 사용자와 봇이 여러 페이지와 작업 간에 어떻게 전환되는지 이해하는 데 도움이 됩니다.

시작하기 전에

  1. reCAPTCHA 환경을 준비합니다.

  2. 점수 기반 키를 만듭니다.

    또는 다음 단계 중 하나를 수행하여 기존 점수 기반 키의 ID를 복사할 수 있습니다.

    • Google Cloud 콘솔에서 기존 키의 ID를 복사하려면 다음을 수행합니다.

      1. reCAPTCHA 페이지로 이동합니다.

        reCAPTCHA로 이동

      2. reCAPTCHA 키 목록에서 복사할 키 위에 마우스 포인터를 올려놓고 를 클릭합니다.
    • REST API를 사용하여 기존 키의 ID를 복사하려면 projects.keys.list 메서드를 사용합니다.
    • gcloud CLI를 사용하여 기존 키의 ID를 복사하려면 gcloud recaptcha keys list 명령어를 사용합니다.

웹사이트에 키 배치

reCAPTCHA는 사이트 상호작용에 대한 컨텍스트가 있을 때 가장 잘 작동합니다. reCAPTCHA는 합법적인 동작과 악의적인 동작을 모두 모니터링하여 사이트 상호작용에 대해 학습합니다.

최상의 결과를 얻으려면 웹사이트의 다음 위치에 점수 기반 키를 설치합니다.

  • 설문지
  • 작업(사용자 상호작용)
  • 모든 웹페이지의 배경

점수 기반 키는 사용자를 방해하지 않으므로 변환에 영향을 주지 않으면서 필요할 때마다 점수 기반 키를 사용하여 reCAPTCHA를 실행할 수 있습니다.

프런트엔드와 키 통합

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

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

데모 웹사이트의 소스 코드에서 각 옵션의 예시를 확인할 수 있습니다.

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

  1. 웹페이지에서 reCAPTCHA를 로드하려면 웹페이지의 <head></head> 요소 내에 점수 기반 키가 있는 JavaScript API를 추가합니다.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>를 지정합니다. 지원되는 언어에 대한 자세한 내용은 reCAPTCHA 언어 코드를 참조하세요.

    배지 위치를 지정하려면 스크립트 태그에서 badge=LOCATION를 쿼리 매개변수로 사용합니다. 예를 들면 www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft입니다. 기본적으로 위치가 bottomright로 설정됩니다. 다른 가능한 값은 inline 및 bottomleft입니다.

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

    1. reCAPTCHA 라이브러리가 로드될 때 grecaptcha.enterprise.execute()가 실행되도록 하려면 grecaptcha.enterprise.ready()를 사용합니다.

    2. 점수 기반 키로 보호하려는 각 상호작용에 대해 grecaptcha.enterprise.execute()를 호출합니다. action 매개변수에서 사용자 상호작용에 의미 있는 이름을 지정합니다. 자세한 내용은 작업을 참조하세요.

      다음 예시에서는 로그인 작업에서 grecaptcha.enterprise.execute()를 호출하는 방법을 보여줍니다.

      <script>
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
    // reCAPTCHA 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>

      grecaptcha.enterprise.execute()는 다음 예시와 같이 토큰을 생성합니다. 

      03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

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

    WAF 통합의 경우 작업 토큰 키를 통합하려면 사전 정의된 요청 헤더에 토큰을 연결해야 하며 평가를 만들지 않아도 됩니다. 자세한 내용은 reCAPTCHA 작업 토큰 구현을 참조하세요.

HTML 버튼에 reCAPTCHA 추가

  1. 웹페이지에서 reCAPTCHA를 로드하려면 웹페이지의 <head></head> 요소 내에 점수 기반 키가 있는 JavaScript API를 추가합니다.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA는 기본적으로 브라우저의 언어를 사용합니다. 다른 언어를 지정하려면 스크립트에서 hl=LANG 속성을 사용합니다. 예를 들어 프랑스어를 사용하려면 <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>를 지정합니다. 지원되는 언어에 대한 자세한 내용은 reCAPTCHA 언어 코드를 참조하세요.

  2. 간단한 HTML 버튼에 reCAPTCHA를 추가하려면 다음을 수행합니다.

    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분 내에 평가를 만듭니다.

    WAF 통합의 경우 작업 토큰 키를 통합하려면 사전 정의된 요청 헤더에 토큰을 연결해야 하며 평가를 만들지 않아도 됩니다. 자세한 내용은 reCAPTCHA 작업 토큰 구현을 참조하세요.

다음 단계