웹사이트용 reCAPTCHA 키 만들기

이 페이지에서는 웹페이지에서 사용자 상호작용을 확인하기 위해 reCAPTCHA 키(키라고도 함)를 만드는 방법을 설명합니다.

reCAPTCHA 키는 웹사이트에 reCAPTCHA가 구성된 방식을 나타냅니다. 이 구성에는 보안문자 챌린지를 표시할지 여부와 같은 중요한 옵션이 포함됩니다.

시작하기 전에

• reCAPTCHA 환경을 준비합니다.
• reCAPTCHA Enterprise 관리자(roles/recaptchaenterprise.admin)라는 Identity and Access Management 역할이 있는지 확인합니다.
• 사용 사례에 가장 적합한 키 유형을 선택합니다.

reCAPTCHA 키 만들기

Google Cloud 프로젝트에 만들 수 있는 reCAPTCHA 키 수에는 제한이 없습니다. 웹사이트당 하나의 reCAPTCHA 키를 만드는 것이 가장 좋습니다.

스테이징 및 프로덕션 환경을 위한 별도의 reCAPTCHA 키를 만드는 것이 좋습니다. 그렇지 않으면 테스트 환경의 데이터로 reCAPTCHA 위험 분석을 오염시킬 위험이 있습니다.

reCAPTCHA 키를 만드는 가장 간단한 방법은 reCAPTCHA 관리 콘솔을 사용하는 것입니다. 또는 Google Cloud 콘솔, reCAPTCHA Enterprise API 또는 Google Cloud CLI를 사용할 수 있습니다.

관리 콘솔

1. reCAPTCHA 관리 콘솔로 이동합니다.

   reCAPTCHA 관리 콘솔로 이동

2. 라벨 입력란에 사이트를 식별하는 데 사용할 이름을 입력합니다.
3. 점수 기반 키를 만들려면 점수 기반(v3)을 선택합니다. 체크박스 키를 만들려면 테스트(v2)를 선택합니다.
4. 도메인을 추가하려면 도메인 이름을 입력하고 아이콘을 클릭합니다.

   도메인을 추가하려면 이 단계를 반복합니다. 도메인을 최대 250개까지 추가할 수 있습니다.

5. Google Cloud 콘솔을 처음 사용하는 경우 서비스 약관을 읽고 체크박스를 선택합니다.
6. 제출을 클릭합니다.

Google Cloud 콘솔을 처음 사용하는 경우 시작할 수 있도록 Google Cloud 프로젝트가 생성되고 필요한 API가 사용 설정됩니다. Google Cloud 프로젝트가 이미 있으면 프로젝트를 시작하는 데 필요한 API가 사용 설정되어 있습니다.

Cloud 콘솔

1. Google Cloud 콘솔에서 reCAPTCHA 페이지로 이동합니다.

   reCAPTCHA로 이동

2. 페이지 상단의 리소스 선택기에 프로젝트 이름이 표시되는지 확인합니다.

   프로젝트 이름이 표시되지 않으면 리소스 선택기를 클릭한 다음 프로젝트를 선택합니다.

3. 키 만들기를 클릭합니다.
4. 표시 이름 필드에 키의 표시 이름을 입력합니다.
5. 플랫폼 유형 선택 메뉴에서 웹사이트를 선택합니다.

   도메인 목록 섹션이 표시됩니다.

6. 웹사이트의 도메인 이름을 입력합니다.

   1. 도메인 목록 섹션에서 도메인 추가를 클릭합니다.
   2. 도메인 필드에 도메인 이름을 입력합니다.

   3. 선택사항: 도메인을 더 추가하려면 도메인 추가를 클릭하고 도메인 필드에 다른 도메인의 이름을 입력합니다. 도메인을 최대 250개까지 추가할 수 있습니다.

      웹사이트의 경우 reCAPTCHA 키는 지정한 도메인과 하위 도메인에 고유합니다. 여러 도메인에서 웹사이트를 제공할 경우 도메인을 2개 이상 지정할 수 있습니다. 도메인을 지정할 때(예: examplepetstore.com)는 하위 도메인(예: subdomain.examplepetstore.com)을 지정할 필요가 없습니다.

      250개가 넘는 도메인에서 키를 사용하려면 도메인 확인 사용 중지 전환 버튼을 클릭합니다. 그러면 reCAPTCHA에서 도메인 목록을 무시합니다. 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

7. 웹사이트용으로 만들려는 reCAPTCHA 키 유형에 따라 적절한 작업을 수행합니다.

점수 기반 reCAPTCHA 키 만들기

참고: 점수 기반 키 만들기는 Google Cloud 콘솔의 기본 옵션입니다.

1. 선택사항: 도메인 확인을 사용 중지하거나 AMP 페이지를 허용하려면 웹 애플리케이션 방화벽(WAF), 도메인 확인, AMP 페이지, 테스트 섹션을 펼칩니다.
   
   1. 도메인과 하위 도메인의 reCAPTCHA 키를 보호하려면 도메인 확인 사용 중지 전환이 사용 중지되어 있는지 확인합니다.

      도메인 확인을 사용 중지하면 사이트에 제한이 없으므로 reCAPTCHA 키를 누구나 액세스하고 사용할 수 있어서 보안 위험이 발생합니다.

      
   2. 점수 기반 키가 Accelerated Mobile Pages(AMP)와 함께 작동하도록 하려면 이 키가 AMP 페이지에서 작동하도록 허용 전환을 사용 설정합니다.

   3. 비프로덕션 환경에서 평가가 생성될 때 키가 반환되도록 하는 점수를 지정하려면 다음을 수행합니다.

      1. 테스트 키입니다 전환 버튼을 클릭합니다.
      2. 점수 상자에 0에서 1.0 사이의 점수를 지정합니다.
      
   4. 키 만들기를 클릭합니다.

   reCAPTCHA 키 페이지에 새로 생성된 키가 나열됩니다.

체크박스 reCAPTCHA 키 만들기

체크박스 키는 정확성을 크게 높이지 못하면서 사용자의 불편만 증가하므로 사용하지 않는 것이 좋습니다.

1. 웹 애플리케이션 방화벽(WAF), 도메인 확인, AMP 페이지, 테스트 섹션을 펼칩니다.
   
2. 도메인과 하위 도메인의 reCAPTCHA 키를 보호하려면 도메인 확인 사용 중지 전환이 사용 중지되어 있는지 확인합니다.

   도메인 확인을 사용 중지하면 사이트에 제한이 없으므로 reCAPTCHA 키를 누구나 액세스하고 사용할 수 있어서 보안 위험이 발생합니다.

   
3. 체크박스 테스트 사용 전환을 사용 설정합니다.
   
4. 적절한 테스트 보안 옵션을 선택합니다.

   테스트 보안 옵션은 식별된 카테고리에 따라 사용자에게 이미지를 선택하라는 메시지가 표시되는 보조 테스트(예: 오토바이 또는 계단이 있는 사진을 선택하세요)가 나타날 가능성을 제어합니다.

   

   사기를 효과적으로 방지하려면 더 어려운 난이도(봇에 대비한 보안)를 선택합니다.

   가장 낮은 테스트 난이도를 선택하면 사용자에게 이미지 테스트가 표시될 가능성이 낮아집니다.

5. 비프로덕션 환경에서 평가가 생성될 때 키가 반환되도록 하는 점수를 지정하려면 다음을 수행합니다.

   1. 테스트 키입니다 전환 버튼을 클릭합니다.
   2. 점수 상자에 0에서 1.0 사이의 점수를 지정합니다.
   3. 적합한 테스트 유형 옵션을 선택합니다.
      • 자동은 가끔 테스트가 표시될 수도 있습니다.
      • 보안문자 없음은 테스트를 표시하지 않습니다.
      • 해결할 수 없는 테스트는 이미지를 표시하지만 테스트는 전달되지 않습니다.
      
   4. 키 만들기를 클릭합니다.

   reCAPTCHA 키 페이지에 새로 생성된 키가 나열됩니다.

gcloud

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

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
• INTEGRATION_TYPE: 통합 유형입니다. 키 유형에 따라 다음 값을 지정합니다.
  • 점수 기반 키의 경우 score
  • 체크박스 키의 경우 checkbox
  참고: 사용자 불편이 증가하고 정확성이 크게 개선되지는 않으므로 CHECKBOX를 사용하지 않는 것이 좋습니다. 자세한 내용은 FAQ를 참조하세요.
• DOMAIN_NAME: 키를 사용할 수 있는 웹사이트의 도메인이나 하위 도메인입니다.

  여러 도메인을 쉼표로 구분된 목록으로 지정합니다.

  250개가 넘는 도메인에서 키를 사용하려면 --allow-all-domains를 지정하여 도메인 확인을 사용 중지하세요. 그러면 reCAPTCHA에서 도메인 목록을 무시합니다. 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

  도메인 확인을 사용 중지하면 사이트에 제한이 없으므로 reCAPTCHA 키를 누구나 액세스하고 사용할 수 있어서 보안 위험이 발생합니다.

  참고: reCAPTCHA 키는 지정된 도메인 및 하위 도메인에 고유합니다. 여러 도메인에서 웹사이트를 제공할 경우 도메인을 2개 이상 지정할 수 있습니다. 도메인(예: examplepetstore.com)을 지정할 때는 하위 도메인(예: subdomain.examplepetstore.com)을 지정할 필요가 없습니다.

gcloud recaptcha keys create 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud recaptcha keys create \
        --web \
        --display-name=DISPLAY_NAME  \
        --integration-type=INTEGRATION_TYPE \
        --domains=DOMAIN_NAME

Windows(PowerShell)

gcloud recaptcha keys create `
        --web `
        --display-name=DISPLAY_NAME  `
        --integration-type=INTEGRATION_TYPE `
        --domains=DOMAIN_NAME

Windows(cmd.exe)

gcloud recaptcha keys create ^
        --web ^
        --display-name=DISPLAY_NAME  ^
        --integration-type=INTEGRATION_TYPE ^
        --domains=DOMAIN_NAME

응답에 새로 생성된 reCAPTCHA 키가 포함됩니다.

REST

키 유형 및 통합 유형에 대한 API 참조 정보는 키 및 통합 유형을 참조하세요.

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

• DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
• INTEGRATION_TYPE: 통합 유형입니다. 키 유형에 따라 다음 값을 지정합니다.
  • 점수 기반 키의 경우 score
  • 체크박스 키의 경우 checkbox
  참고: 사용자 불편이 증가하고 정확성이 크게 개선되지는 않으므로 CHECKBOX를 사용하지 않는 것이 좋습니다. 자세한 내용은 FAQ를 참조하세요.
• DOMAIN_NAME: 키를 사용할 수 있는 웹사이트의 도메인이나 하위 도메인입니다.

  여러 도메인을 쉼표로 구분된 목록으로 지정합니다.

  250개가 넘는 도메인에서 키를 사용하려면 --allow-all-domains를 지정하여 도메인 확인을 사용 중지하세요. 그러면 reCAPTCHA에서 도메인 목록을 무시합니다. 자신이 만든 평가에서 tokenProperties.hostname 필드를 검토하여 도메인 확인을 직접 수행해야 합니다.

  도메인 확인을 사용 중지하면 사이트에 제한이 없으므로 reCAPTCHA 키를 누구나 액세스하고 사용할 수 있어서 보안 위험이 발생합니다.

  참고: reCAPTCHA 키는 지정된 도메인 및 하위 도메인에 고유합니다. 여러 도메인에서 웹사이트를 제공할 경우 도메인을 2개 이상 지정할 수 있습니다. 도메인(예: examplepetstore.com)을 지정할 때는 하위 도메인(예: subdomain.examplepetstore.com)을 지정할 필요가 없습니다.

HTTP 메서드 및 URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

JSON 요청 본문:

{
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowedDomains": "DOMAINS",
    "integrationType": "TYPE_OF_INTEGRATION"
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

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/6Ldqgs0UAAAAAIn4k7YxEB-LwEh5S9-Gv6IIWB8m",
  "displayName": "DISPLAY_NAME",
  "webSettings": {
    "allowAllDomains": false,
    "allowedDomains": [
      DOMAINS
    ],
    "allowAmpTraffic": false,
    "integrationType": "SCORE",
    "challengeSecurityPreference": "CHALLENGE_SECURITY_PREFERENCE_UNSPECIFIED"
  }
}

참고: reCAPTCHA 키를 만든 후에는 수정하거나 삭제할 수 있습니다. 삭제된 키를 복구할 수 없습니다. 또한 reCAPTCHA 키를 한 Google Cloud 프로젝트에서 다른 Google Cloud 프로젝트로 마이그레이션할 수 없습니다.

(선택사항) 기존 reCAPTCHA 보안 비밀 키 찾기

reCAPTCHA Enterprise API를 사용하지 않는 서드 파티 애플리케이션과 통합하려면 기존 보안 비밀 키가 필요합니다.

사용자가 만든 모든 사이트 키에 reCAPTCHA가 서드 파티 애플리케이션에 사용할 수 있는 기존 reCAPTCHA 보안 비밀 키(기존 보안 비밀 키)를 만듭니다.

참고: 사용자에게 표시되고 공격자가 애플리케이션을 악용할 수 있으므로 프런트엔드에서는 기존 보안 비밀 키를 사용하지 않는 것이 좋습니다.

기존 보안 비밀 키를 찾으려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 reCAPTCHA 페이지로 이동합니다.

   reCAPTCHA로 이동

2. reCAPTCHA 키 섹션에서 자신이 만든 reCAPTCHA 키를 찾아서 키를 클릭합니다.

   

3. 키 세부정보 페이지의 통합 탭에서 기존 키 사용을 클릭합니다. 기존 보안 비밀 키를 사용하는 방법에 대한 안내가 표시된 대화상자가 열립니다.

   

다음 단계

• 웹페이지에 점수 기반 키 설치
• 웹페이지에 체크박스 키 설치