웹사이트에서 계정 관련 허위 행위 감지 및 방지

이 문서에서는 reCAPTCHA 계정 방어 도구를 사용하여 웹사이트에서 계정 관련 사기 활동을 감지하고 방지하는 방법을 설명합니다.

reCAPTCHA를 사용하면 로그인 및 결제 같은 중요한 작업을 보호할 수 있습니다. 그러나 미묘한 유형의 계정 악용도 많이 존재하는데, 이런 행동은 일정 기간 동안 웹사이트에서 특정 사용자의 행동을 관찰해야 탐지할 수 있습니다. reCAPTCHA 계정 방어 도구는 웹사이트에서 의심스러운 사이트 트렌드나 활동의 변화를 감지하기 위해 사이트별 모델을 생성함으로 이러한 유형의 미묘한 악용을 식별하는 데 도움이 됩니다. reCAPTCHA 계정 방어 도구는 사이트별 모델을 사용하여 다음을 감지할 수 있습니다.

  • 의심스러운 활동
  • 활동이 비슷한 계정
  • 특정 사용자에게 신뢰할 수 있다고 표시된 기기에서 들어오는 요청

reCAPTCHA 계정 방어 도구 및 사이트별 모델의 분석을 기반으로 다음을 수행할 수 있습니다.

  • 사기 계정 제한 또는 사용 중지
  • 계정 탈취 시도 방지
  • 성공적인 계정 탈취로 인한 피해 완화
  • 적법한 사용자 계정에서 전송된 요청에만 액세스 권한 부여
  • 신뢰할 수 있는 기기 중 하나에서 로그인하는 사용자의 불편 경감

시작하기 전에

  1. reCAPTCHA 환경을 준비합니다.
  2. 점수 기반 사이트 키를 만듭니다.

reCAPTCHA 계정 방어 도구의 웹페이지 구성

reCAPTCHA 계정 방어 도구의 효과적인 감지를 위해서는 계정 활동을 포괄적으로 이해해야 합니다. reCAPTCHA 계정 방어 도구에 계정 관련 활동 제공을 시작하고 사이트별 모델을 만들고 개선하려면 다음을 수행합니다.

  1. 수평 원격 분석 데이터 수집 사용 설정
  2. 중요한 사용자 작업 보고
  3. 중요한 사용자 이벤트 평가
  4. 사용자 이벤트에 주석을 추가하여 사이트별 모델 조정

수평 원격 분석 데이터 수집 사용 설정

reCAPTCHA 계정 방어 도구는 사용자가 로그인했거나 로그인하도록 유도되는지와 같은 사용자 작업에 대한 완전한 이해가 필요합니다. reCAPTCHA 계정 방어 도구에 따라 수평 원격 분석 데이터에 대한 수동 수집을 사용 설정하려면 사용자 워크플로에 포함된 모든 웹페이지의 백그라운드에서 이전에 만든 점수 기반 사이트 키를 사용해서 reCAPTCHA JavaScript 스크립트를 로드합니다.

다음 예시는 웹페이지에서 reCAPTCHA JavaScript 스크립트를 로드하는 방법을 보여줍니다.

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

중요한 사용자 작업 보고

의심스러운 활동 패턴을 감지하고 사이트에서 일반적인 활동 패턴을 더 효과적으로 이해하기 위해 reCAPTCHA 계정 방어 도구는 중요한 사용자 작업에 대한 정보가 필요합니다. 따라서 중요한 사용자 작업에서 grecaptcha.enterprise.execute()를 호출하여 웹페이지에서 중요한 사용자 작업을 보고합니다.

추가적인 신호 수집에 도움이 되기 때문에 모든 중요한 사용자 작업을 보고하는 것이 좋습니다. 보고하려는 모든 사용자 작업에 대해 grecaptcha.enterprise.execute()의 action 매개변수 값을 사용자 작업을 기술하는 작업 이름으로 바꿉니다.

다음 표에서는 중요한 사용자 작업을 보고할 때 사용할 수 있는 작업 이름을 보여줍니다.

작업 이름 사용자 시작 이벤트 또는 사용자 작업
LOGIN

웹사이트에 로그인합니다.
REGISTRATION 웹사이트 등록.
SECURITY_QUESTION_CHANGE 보안 질문 변경을 요청합니다.
PASSWORD_RESET 비밀번호 재설정을 요청합니다.
PHONE_NUMBER_UPDATE 전화번호 업데이트를 요청합니다.
EMAIL_UPDATE 이메일 주소 업데이트를 요청합니다.
ACCOUNT_UPDATE 연락처 세부정보와 같은 계정 관련 정보를 업데이트하도록 요청합니다.
TRIGGER_MFA MFA 챌린지를 트리거하는 작업입니다.
REDEEM_CODE 코드 사용을 요청합니다.
LIST_PAYMENT_METHODS 결제 수단 목록을 가져옵니다.

다음 예시는 전화번호 업데이트 시 grecaptcha.enterprise.execute()를 호출하는 방법을 보여줍니다.

    <script>
    function onClick(e) {
      e.preventDefault();
      grecaptcha.enterprise.ready(async () => {
        const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'});
      });
    }
    </script>

중요한 사용자 이벤트 평가

사용자 작업에서 grecaptcha.enterprise.execute()를 호출하면 토큰이 생성됩니다. 성공 및 실패한 로그인, 등록, 로그인한 사용자의 작업과 같은 중요한 사용자 이벤트에 대해 grecaptcha.enterprise.execute() 호출 결과를 평가하는 평가를 만듭니다. 이러한 평가는 잠재적인 허위 행위를 처리하는 방법을 결정할 때 사용하는 위험 판정을 제공합니다. 수행 가능한 작업 중 일부는 의심스러운 요청 차단, 위험한 로그인 시도, 관심 계정 조사입니다.

reCAPTCHA 계정 방어 도구를 사용하려면 로그인 요청, 로그인한 요청, 가입 요청과 같은 사용자 활동을 특정 계정에서 발생한 것으로 확인하기 위해 안정적인 계정 식별자를 제공해야 합니다. 그러면 reCAPTCHA 계정 방어 도구가 사용자 활동 패턴을 이해하고 각 계정의 활동 모델을 빌드하여 비정상 트래픽과 악의적인 트래픽을 더욱 효과적으로 감지할 수 있습니다.

사용자가 자주 변경하지 않는 안정적인 계정 식별자 accountId를 선택하고 projects.assessments.create 메서드의 평가에 제공합니다. 이 안정적인 계정 식별자는 동일한 사용자와 관련된 모든 이벤트에서 같은 값이어야 합니다. 계정 식별자로 다음을 제공할 수 있습니다.

사용자 식별자

모든 계정을 안정적인 사용자 이름, 이메일 주소 또는 전화번호와 고유하게 연결할 수 있는 경우 accountId로 사용할 수 있습니다. 이러한 교차 사이트 식별자(사이트 간에 재사용할 수 있는 식별자)를 제공하면 reCAPTCHA가 이 정보를 사용하여 악용 계정 식별자를 신고하고 이러한 식별자와 관련된 교차 사이트 악용 패턴에 대한 지식을 사용하여 교차 사이트 모델을 기반으로 사용자 계정 보호를 강화할 수 있습니다.

또는 각 계정과 고유하게 연결된 내부 사용자 ID가 있으면 이를 accountId로 제공할 수 있습니다.

해싱 또는 암호화됨

각 계정에 고유하게 연결된 내부 사용자 ID가 없는 경우 안정적인 식별자를 사이트별 불확실한 계정 식별자로 전환할 수 있습니다. 이 식별자는 reCAPTCHA 계정 방어 도구가 사용자 활동 패턴을 이해하고 비정상적인 동작을 감지하는 데 필요하지만 다른 사이트 간에 공유되지는 않습니다.

reCAPTCHA에 전송하기 전에 안정적인 계정 식별자를 선택하고 암호화 또는 해싱을 사용하여 불확실하게 만듭니다.

  • 암호화(권장): 안정적인 암호문을 생성하는 확정적 암호화 메서드를 사용하여 계정 식별자를 암호화합니다. 자세한 안내는 확정적으로 데이터 암호화를 참조하세요. 해싱 대신 대칭적 암호화를 선택할 경우 사용자 식별자와 해당 불확실한 사용자 식별자 간에 매핑을 유지할 필요가 없습니다. reCAPTCHA에서 반환하는 불확실한 식별자를 복호화하여 사용자 식별자로 변환합니다.

  • 해싱: SHA256-HMAC 메서드를 사용하여 원하는 커스텀 솔트로 계정 식별자를 해싱하는 것이 좋습니다. 해시는 단방향이므로, 원래 계정으로 다시 반환할 수 있는 해시된 계정 식별자를 매핑할 수 있도록 생성된 해시와 사용자 식별자 간에 매핑을 유지해야 합니다.

모든 계정 관련 요청에 안정적인 계정 식별자를 제공하는 것 외에도 일부 특정 요청에 불안정할 수 있는 추가 계정 식별자를 제공할 수 있습니다. accountId 외에 제공되는 컨텍스트별 계정 식별자는 reCAPTCHA 계정 방어 도구가 사용자 활동을 더 잘 이해하고 계정 탈취 시도를 감지하여 사용자 계정을 안전하게 유지하는 데 도움이 됩니다. 추가 식별자를 제공하면 reCAPTCHA가 이 정보를 사용하여 악용 계정 식별자를 신고하고 이러한 식별자와 관련된 교차 사이트 악용 패턴에 대한 지식을 사용하여 교차 사이트 모델을 기반으로 사용자 계정 보호를 강화할 수 있습니다. 예를 들어 다음을 제공할 수 있습니다.

  • 로그인 요청을 위해 로그인 핸들로 사용된 사용자 이름, 이메일 주소 또는 전화번호

  • 다중 인증(MFA) 요청을 위해 인증된 이메일 주소 또는 전화번호

  • 계정 업데이트를 요청하는 동안 사용자가 제공한 이메일 주소 또는 전화번호(기본 또는 보조)

  • 등록 요청 중에 사용자가 제공한 이메일 주소 및 전화번호

선택한 안정적인 계정 식별자를 모든 계정 관련 요청 projects.assessments.create 메서드의 accountId 매개변수에 추가합니다. 원하는 경우 평가에서 userIds 필드를 사용하여 관련 요청에 추가 계정 식별자를 제공합니다.

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

  • PROJECT_ID: Google Cloud 프로젝트 ID
  • TOKEN: grecaptcha.enterprise.execute() 호출에서 반환 토큰
  • KEY_ID: 사이트와 연결된 reCAPTCHA 키
  • ACCOUNT_ID: 웹사이트의 사용자 계정에 대해 해당 사용자 계정과 고유하게 연결된 식별자
  • EMAIL_ADDRESS: (선택사항) 이 요청과 연결된 이메일 주소(있는 경우)
  • PHONE_NUMBER: (선택사항) 이 요청과 연결된 전화번호(있는 경우)
  • USERNAME: (선택사항) 이 요청과 연결된 사용자 이름(있는 경우)

HTTP 메서드 및 URL: 

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

JSON 요청 본문:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "userInfo": {
      "accountId": "ACCOUNT_ID",
      "userIds": [
        {
          "email": "EMAIL_ADDRESS"
        },
        {
          "phoneNumber": "PHONE_NUMBER"
        },
        {
          "username": "USERNAME"
        }
      ]
    }
  }
}

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

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/assessments"

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/assessments" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "login",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.6,
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "userInfo": {
      "accountId": "ACCOUNT_ID"
    }
  },
  "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000",
  "accountDefenderAssessment": {
    "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"]
  }
}

코드 샘플

Java

reCAPTCHA에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AccountDefenderAssessment.AccountDefenderLabel;
import com.google.recaptchaenterprise.v1.Assessment;
import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
import com.google.recaptchaenterprise.v1.Event;
import com.google.recaptchaenterprise.v1.ProjectName;
import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
import com.google.recaptchaenterprise.v1.TokenProperties;
import com.google.recaptchaenterprise.v1.UserId;
import com.google.recaptchaenterprise.v1.UserInfo;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.List;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AccountDefenderAssessment {

  public static void main(String[] args)
      throws IOException, NoSuchAlgorithmException, InvalidKeyException {
    // TODO(developer): Replace these variables before running the sample.
    // projectId: Google Cloud Project ID
    String projectId = "project-id";

    // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha
    // services.
    String recaptchaSiteKey = "recaptcha-site-key";

    // token: The token obtained from the client on passing the recaptchaSiteKey.
    // To get the token, integrate the recaptchaSiteKey with frontend. See,
    // https://cloud.google.com/recaptcha-enterprise/docs/instrument-web-pages#frontend_integration_score
    String token = "recaptcha-token";

    // recaptchaAction: The action name corresponding to the token.
    String recaptchaAction = "recaptcha-action";

    // Unique ID of the user, such as email, customer ID, etc.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    // User phone number
    String phoneNumber = "555-987-XXXX";

    // User email address
    String emailAddress = "john.doe@example.com";

    accountDefenderAssessment(projectId, recaptchaSiteKey, token, recaptchaAction, accountId, phoneNumber, emailAddress);
  }

  /**
   * This assessment detects account takeovers. See,
   * https://cloud.google.com/recaptcha-enterprise/docs/account-takeovers The input is the hashed
   * account id. Result tells if the action represents an account takeover. You can optionally
   * trigger a Multi-Factor Authentication based on the result.
   */
  public static void accountDefenderAssessment(
      String projectId,
      String recaptchaSiteKey,
      String token,
      String recaptchaAction,
      String accountId,
      String phoneNumber,
      String emailAddress)
      throws IOException {
    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

      // Set the properties of the event to be tracked.
      Event.Builder eventBuilder =
          Event.newBuilder()
              .setSiteKey(recaptchaSiteKey)
              .setToken(token);

      // Set the account id, email address and phone number (of the user).
      eventBuilder.setUserInfo(
        UserInfo.newBuilder()
          .setAccountId(accountId)
          .addUserIds(UserId.newBuilder().setEmail(emailAddress))
          .addUserIds(UserId.newBuilder().setPhoneNumber(phoneNumber)));

      Event event = eventBuilder.build();

      // Build the assessment request.
      CreateAssessmentRequest createAssessmentRequest =
          CreateAssessmentRequest.newBuilder()
              .setParent(ProjectName.of(projectId).toString())
              .setAssessment(Assessment.newBuilder().setEvent(event).build())
              .build();

      Assessment response = client.createAssessment(createAssessmentRequest);

      // Check integrity of the response token.
      if (!checkTokenIntegrity(response.getTokenProperties(), recaptchaAction)) {
        return;
      }

      // Get the reason(s) and the reCAPTCHA risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }
      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));

      // Get the Account Defender result.
      com.google.recaptchaenterprise.v1.AccountDefenderAssessment accountDefenderAssessment =
          response.getAccountDefenderAssessment();
      System.out.println(accountDefenderAssessment);

      // Get Account Defender label.
      List<AccountDefenderLabel> defenderResult =
          response.getAccountDefenderAssessment().getLabelsList();
      // Based on the result, can you choose next steps.
      // If the 'defenderResult' field is empty, it indicates that Account Defender did not have
      // anything to add to the score.
      // Few result labels: ACCOUNT_DEFENDER_LABEL_UNSPECIFIED, PROFILE_MATCH,
      // SUSPICIOUS_LOGIN_ACTIVITY, SUSPICIOUS_ACCOUNT_CREATION, RELATED_ACCOUNTS_NUMBER_HIGH.
      // For more information on interpreting the assessment, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/account-defender#interpret-assessment-details
      System.out.println("Account Defender Assessment Result: " + defenderResult);
    }
  }

  private static boolean checkTokenIntegrity(
      TokenProperties tokenProperties, String recaptchaAction) {
    // Check if the token is valid.
    if (!tokenProperties.getValid()) {
      System.out.println(
          "The Account Defender Assessment call failed because the token was: "
              + tokenProperties.getInvalidReason().name());
      return false;
    }

    // Check if the expected action was executed.
    if (!tokenProperties.getAction().equals(recaptchaAction)) {
      System.out.printf(
          "The action attribute in the reCAPTCHA tag '%s' does not match "
              + "the action '%s' you are expecting to score",
          tokenProperties.getAction(), recaptchaAction);
      return false;
    }
    return true;
  }
}

중요한 사용자 이벤트의 위험 판정 해석

계정 방어 도구가 사용 설정된 평가를 만들면 계정 방어 도구가 평가 응답의 일부로 accountDefenderAssessment를 반환합니다. accountDefenderAssessment 값은 사용자 활동이 합법적인지 또는 사기인지 평가하는 데 도움이 됩니다. 또한 사용자 이벤트에 주석을 추가할 때 사용해야 하는 평가 ID를 반환합니다.

다음 예시는 샘플 JSON 응답입니다.

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "login",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.6,
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY_ID",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000X",
  "accountDefenderAssessment": {
    labels: ["SUSPICIOUS_LOGIN_ACTIVITY"]
  }
}

accountDefenderAssessment 필드에는 다음 값이 포함될 수 있습니다.

값 설명
SUSPICIOUS_LOGIN_ACTIVITY 해당 요청이 사용자 인증 정보 채우기 또는 계정 탈취의 위험이 높음을 나타냅니다.
SUSPICIOUS_ACCOUNT_CREATION 해당 요청이 악용되는 계정을 만들 위험이 높음을 나타냅니다.
PROFILE_MATCH

사용자 속성이 이전에 이 특정 사용자에 표시된 속성과 일치함을 나타냅니다. 이 값은 이 사용자가 이전에 웹사이트에 액세스하는 데 사용한 신뢰할 수 있는 기기에 있음을 나타냅니다.

PROFILE_MATCH는 다음 시나리오에서만 반환됩니다.

  • 사용자가 다단계(MFA) 또는 2단계 인증(2FA)을 사용할 때 사용자가 MFA 또는 2FA 챌린지를 통과한 후 reCAPTCHA 계정 방어 도구가 사용자 프로필을 신뢰할 수 있는 것으로 표시하는 경우
  • 사용자가 평가를 LEGITIMATE 또는 PASSED_TWO_FACTOR로 주석 처리하며 reCAPTCHA 계정 방어 도구가 해당 사용자 프로필을 신뢰할 수 있는 것으로 표시하는 경우
RELATED_ACCOUNTS_NUMBER_HIGH 요청에 관련 계정이 많음을 나타냅니다. 계정이 반드시 잘못된 것은 아니지만 추가 조사가 필요할 수 있습니다.

이벤트에 주석을 추가하여 사이트별 모델 조정

reCAPTCHA 계정 방어 도구에 추가 정보를 제공하고 사이트별 감지 모델을 개선하려면 평가를 만들어서 평가한 이벤트에 주석을 추가해야 합니다.

평가 ID를 사용해서 projects.assessments.annotate 메서드에 요청을 전송하여 평가에 주석을 추가합니다. 요청 본문에 평가에 설명된 이벤트에 대한 추가 정보를 제공하는 라벨을 포함합니다.

평가에 주석을 추가하려면 다음을 수행합니다.

  1. 사용 사례에 따라 요청 JSON 본문에 추가할 정보 및 라벨을 결정합니다.

    다음 표에는 이벤트에 주석을 추가하는 데 사용할 수 있는 라벨과 값이 나와 있습니다.

    라벨 설명 요청 예시
    reasons 필수 항목. 평가를 지원하는 라벨입니다.

    실시간 감지에 영향을 주기 때문에 이벤트 발생 후 몇 초 또는 몇 분 이내에 reasons 라벨에 실시간 이벤트 세부정보를 제공합니다.

    가능한 값 목록은 이유 값을 참조하세요.

    예시: 계정 탈취를 감지하려면 입력한 비밀번호가 CORRECT_PASSWORD 또는 INCORRECT_PASSWORD 값에 올바른지 주석을 추가합니다. 자체 MFA를 배포한 경우 INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR, FAILED_TWO_FACTOR 값을 추가할 수 있습니다. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation 선택사항. 평가 적법성을 나타내는 라벨입니다.

    annotation 라벨에서 위험 평가를 검증하거나 수정하기 위해 로그인 및 등록 이벤트에 대한 사실을 제공합니다.

    가능한 값은 LEGITIMATE 또는 FRAUDULENT입니다.

    이 정보는 언제든지 또는 일괄 작업을 통해 전송할 수 있습니다. 하지만 실시간 감지에 영향을 주기 때문에 이벤트 후 몇 초 또는 몇 분 이내에 이 정보를 전송하는 것이 좋습니다.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    선택사항. 계정 ID를 이벤트와 연결하는 라벨입니다.

    계정 ID 없이 평가를 생성한 경우 사용 가능할 때마다 이 라벨을 사용하여 이벤트의 계정 ID를 제공합니다.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. 적절한 라벨을 사용하여 주석 요청을 만듭니다.

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

    • ASSESSMENT_ID: projects.assessments.create 호출에서 반환된 name 필드 값입니다.
    • ANNOTATION: (선택사항) 평가가 타당한지 또는 허위인지를 나타내는 라벨입니다.
    • REASONS: 선택사항. 주석을 지원하는 이유입니다. 가능한 값 목록은 이유 값을 참조하세요.
    • ACCOUNT_ID: 선택사항입니다. 웹사이트의 사용자 계정과 고유하게 연결된 식별자입니다.

    자세한 내용은 주석 라벨을 참조하세요.

    HTTP 메서드 및 URL:

    POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

    JSON 요청 본문:

    {
  "annotation": ANNOTATION,
  "reasons": REASONS,
  "accountId": ACCOUNT_ID
}

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

    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/ASSESSMENT_ID:annotate"

    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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    성공 상태 코드(2xx)와 빈 응답을 받게 됩니다.

코드 샘플

Java

reCAPTCHA에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요. 


import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.protobuf.ByteString;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Annotation;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentRequest.Reason;
import com.google.recaptchaenterprise.v1.AnnotateAssessmentResponse;
import com.google.recaptchaenterprise.v1.AssessmentName;
import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.util.UUID;

public class AnnotateAccountDefenderAssessment {

  public static void main(String[] args) throws IOException, NoSuchAlgorithmException {
    // TODO(developer): Replace these variables before running the sample.
    // projectID: GCloud Project id.
    String projectID = "project-id";

    // assessmentId: Value of the 'name' field returned from the CreateAssessment call.
    String assessmentId = "account-defender-assessment-id";

    // accountId: Set the accountId corresponding to the assessment id.
    String accountId = "default" + UUID.randomUUID().toString().split("-")[0];

    annotateAssessment(projectID, assessmentId, accountId);
  }

  /**
   * Pre-requisite: Create an assessment before annotating. Annotate an assessment to provide
   * feedback on the correctness of recaptcha prediction.
   */
  public static void annotateAssessment(
      String projectID, String assessmentId, String accountId) throws IOException {

    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {
      // Build the annotation request.
      // For more info on when/how to annotate, see:
      // https://cloud.google.com/recaptcha-enterprise/docs/annotate-assessment#when_to_annotate
      AnnotateAssessmentRequest annotateAssessmentRequest =
          AnnotateAssessmentRequest.newBuilder()
              .setName(AssessmentName.of(projectID, assessmentId).toString())
              .setAnnotation(Annotation.LEGITIMATE)
              .addReasons(Reason.PASSED_TWO_FACTOR)
              .setAccountId(accountId)
              .build();

      // Empty response is sent back.
      AnnotateAssessmentResponse response = client.annotateAssessment(annotateAssessmentRequest);
      System.out.println("Annotated response sent successfully ! " + response);
    }
  }
}

reCAPTCHA 계정 방어 도구 사용 설정

reCAPTCHA 계정 방어 도구의 웹페이지를 구성한 후에 reCAPTCHA 계정 방어 도구를 사용 설정할 수 있습니다.

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

    reCAPTCHA로 이동

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

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

  3. 설정 클릭합니다.

  4. 계정 방어 도구 창에서 구성을 클릭합니다.

  5. 계정 방어 도구 구성 대화상자에서 사용 설정을 클릭한 후 저장을 클릭합니다.

reCAPTCHA 계정 방어 도구 사용 설정이 Google 시스템에 전파되는 데 몇 시간이 걸릴 수 있습니다. 기능 사용 설정이 Google 시스템에 전파되면 평가의 일환으로 계정 방어 도구와 관련된 응답을 받아야 합니다.

다음 단계