모바일 애플리케이션에서 계정 관련 허위 행위 감지 및 방지

reCAPTCHA 계정 방어 도구를 사용하여 모바일 애플리케이션에서 계정 관련 허위 행위를 감지하고 방지하는 방법을 보여주는 문서입니다.

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

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

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

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

시작하기 전에

1. 프로젝트에 결제 계정을 추가하여 자동 보안 검토를 트리거한 후 모바일 애플리케이션용 reCAPTCHA 계정 방어 도구에 액세스할 수 있습니다. 이 기능에 사이트를 온보딩하려면 프로젝트에 결제 계정을 추가하세요.
2. reCAPTCHA 환경을 준비합니다.
3. 점수 기반 키를 만듭니다.

reCAPTCHA 계정 방어 도구용 모바일 애플리케이션 구성

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

1. reCAPTCHA를 모바일 애플리케이션과 통합합니다.

   • Android 앱의 경우 Android 앱과 reCAPTCHA 통합을 참조하세요.
   • iOS 앱의 경우 iOS 앱에 reCAPTCHA 통합을 참조하세요.
2. 중요한 사용자 작업 보고
3. 중요한 사용자 이벤트 평가
4. 사용자 이벤트에 주석을 추가하여 사이트별 모델 조정

중요한 사용자 작업 보고

의심스러운 활동 패턴을 감지하고 사이트에서 일반적인 활동 패턴을 더 효과적으로 이해하기 위해 reCAPTCHA 계정 방어 도구는 중요한 사용자 작업에 대한 정보가 필요합니다. reCAPTCHA를 통해 보호되는 앱의 각 작업에 대해 RecaptchaAction으로 execute() 메서드를 호출합니다. execute() 및 RecaptchaAction에 대한 자세한 내용은 다음을 참조하세요.

• Android: execute() 및 RecaptchaAction.
• iOS: execute() 및 RecaptchaAction.

reCAPTCHA는 기본 제공 작업 집합을 제공하며 필요한 경우 커스텀 작업을 만들 수 있습니다.

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

참고: 작업 이름은 다음 목록으로 제한될 필요가 없습니다. custom() for Android 또는 custom() for iOS를 사용하여 의미 있는 작업 이름을 추가하고 PASSWORD_RESET 또는 ACCOUNT_UPDATE와 같은 사용자 작업을 설명할 수 있습니다.

작업 이름	사용자 시작 이벤트 또는 사용자 작업
LOGIN	모바일 애플리케이션에 로그인
SIGNUP	모바일 애플리케이션에 가입

중요한 사용자 이벤트 평가

사용자 작업에서 execute()를 호출하면 토큰이 생성됩니다. 성공 및 실패한 로그인, 등록, 로그인한 사용자의 작업과 같은 중요한 사용자 이벤트에 대해 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: 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

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

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

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

{
  "tokenProperties": {
    "valid": true,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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"]
  }
}

참고: 이미 기존의 hashedAccountId 파라미터를 사용하여 projects.assessments.create 메서드에 안정적인 계정 식별자를 제공하는 경우, 계속 그렇게 하셔도 됩니다. 그러나 hashedAccountId는 지원 중단되었으므로 새 통합에서는 accountId 파라미터를 사용해야 합니다

코드 샘플

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 = "[e-mail]";

    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,
    "androidPackageName": "com.example.app" or "iosBundleId": "com.example.app",
    "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 계정 방어 도구가 해당 사용자 프로필을 신뢰할 수 있는 것으로 표시하는 경우

참고:accountDefenderAssessment 필드가 비어 있으면 reCAPTCHA 계정 방어 도구가 점수에 추가할 항목이 없음을 나타냅니다.

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

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

   참고: 다음 명령어는 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/ASSESSMENT_ID:annotate"

   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/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. 계정 방어 도구 구성 대화상자에서 사용 설정을 클릭한 다음 저장을 클릭합니다.

   참고: Google Cloud 콘솔에서 이 기능을 사용 설정할 수 없는 경우 프로젝트에 결제 계정을 추가하여 자동 보안 검토를 트리거하세요.
   

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

다음 단계

• 기타 계정 보호 기능에 대해 자세히 알아보려면 사용자 계정 보호 기능 참조하기