Mendeteksi dan mencegah aktivitas penipuan terkait akun di situs

Account defense membantu Anda mendeteksi dan mencegah aktivitas akun yang bersifat menipu di situs. Account defense memantau pola aktivitas pengguna dan membangun model perilaku khusus situs untuk membantu Anda mengidentifikasi penyalahgunaan kredensial dan melindungi akun pengguna dari serangan otomatis.

Fraud Defense membantu Anda melindungi tindakan penting, seperti login dan checkout. Namun, ada banyak bentuk penyalahgunaan akun yang tidak kentara yang dapat dideteksi dengan mengamati perilaku pengguna tertentu di situs selama jangka waktu tertentu. Account defense, fitur Fraud Defense, membantu mengidentifikasi jenis penyalahgunaan yang tidak kentara ini dengan membuat model khusus situs untuk situs Anda guna mendeteksi tren perilaku mencurigakan atau perubahan aktivitas. Dengan menggunakan model khusus situs, Account defense membantu Anda mendeteksi hal berikut:

  • Aktivitas mencurigakan
  • Akun dengan perilaku serupa
  • Permintaan yang berasal dari perangkat yang ditandai sebagai tepercaya untuk pengguna tertentu

Berdasarkan analisis Account defense dan model khusus situs, Anda dapat melakukan tindakan berikut:

  • Membatasi atau menonaktifkan akun penipuan.
  • Mencegah upaya pengambilalihan akun.
  • Memitigasi pengambilalihan akun yang berhasil.
  • Memberikan akses hanya ke permintaan yang berasal dari akun pengguna yang sah.
  • Mengurangi hambatan bagi pengguna yang login dari salah satu perangkat tepercaya mereka.

Sebelum memulai

  1. Menyiapkan lingkungan Anda untuk Google Cloud Fraud Defense.
  2. Buat kunci situs berbasis skor.

Mengonfigurasi halaman web Anda untuk Account defense

Account defense memerlukan pemahaman yang komprehensif tentang aktivitas akun untuk memungkinkan deteksi yang efektif. Untuk mulai memasukkan aktivitas terkait akun ke Account defense, serta membuat dan meningkatkan kualitas model khusus situs Anda, lakukan hal berikut:

  1. Aktifkan pengumpulan data telemetri horizontal.
  2. Mendapatkan laporan tentang tindakan penting pengguna.
  3. Menilai peristiwa pengguna yang penting.
  4. Beri anotasi pada peristiwa pengguna untuk menyesuaikan model khusus situs Anda.

Mengaktifkan pengumpulan data telemetri horizontal

Account defense memerlukan tampilan lengkap tindakan pengguna, seperti apakah pengguna sudah login atau akan login. Untuk mengaktifkan pengumpulan pasif data telemetri horizontal oleh Account defense, muat skrip JavaScript reCAPTCHA dengan kunci situs berbasis skor yang Anda buat di latar belakang semua halaman web yang merupakan bagian dari alur kerja pengguna Anda.

Contoh berikut menunjukkan cara memuat skrip JavaScript reCAPTCHA di halaman web.

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

Mendapatkan laporan tindakan penting pengguna

Untuk mendeteksi pola aktivitas mencurigakan dan membangun model yang lebih baik dari pola aktivitas umum di situs Anda, Account defense memerlukan informasi tentang tindakan pengguna yang penting. Oleh karena itu, laporkan tindakan pengguna yang penting di halaman web dengan memanggil grecaptcha.enterprise.execute() pada tindakan pengguna yang penting tersebut.

Sebaiknya laporkan semua tindakan penting pengguna karena hal ini membantu pengumpulan sinyal tambahan. Untuk setiap tindakan pengguna yang ingin Anda laporkan, ganti nilai parameter action dari grecaptcha.enterprise.execute() dengan nama tindakan yang mendeskripsikan tindakan pengguna.

Tabel berikut mencantumkan nama tindakan yang dapat Anda gunakan saat melaporkan tindakan penting pengguna.

Nama tindakan Peristiwa yang dimulai pengguna atau tindakan pengguna
LOGIN

Login ke situs.
REGISTRATION Pendaftaran di situs.
SECURITY_QUESTION_CHANGE Minta untuk mengubah pertanyaan keamanan.
PASSWORD_RESET Minta reset sandi.
PHONE_NUMBER_UPDATE Permintaan untuk memperbarui nomor telepon.
EMAIL_UPDATE Permintaan untuk memperbarui alamat email.
ACCOUNT_UPDATE Permintaan untuk memperbarui informasi terkait akun, seperti detail kontak.
TRIGGER_MFA Tindakan yang memicu verifikasi MFA.
REDEEM_CODE Minta penukaran kode.
LIST_PAYMENT_METHODS Mengambil daftar metode pembayaran.

Contoh berikut menunjukkan cara memanggil grecaptcha.enterprise.execute() pada pembaruan nomor telepon:

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

Menilai peristiwa pengguna yang penting

Saat Anda memanggil grecaptcha.enterprise.execute() pada tindakan pengguna, tindakan tersebut akan menghasilkan token. Untuk peristiwa pengguna yang penting, seperti login yang berhasil dan gagal, pendaftaran, dan tindakan pengguna yang login, buat penilaian untuk menilai hasil panggilan grecaptcha.enterprise.execute(). Penilaian memberi Anda verdict risiko, yang dapat Anda gunakan untuk membuat keputusan tentang cara menangani aktivitas penipuan. Beberapa tindakan yang dapat Anda lakukan adalah memblokir permintaan yang mencurigakan, menantang login yang berisiko, dan menyelidiki akun yang menarik.

Account defense mengharuskan Anda memberikan ID akun yang stabil untuk melakukan penilaian dan mengatribusikan aktivitas pengguna–seperti permintaan login, permintaan yang login, dan permintaan pendaftaran–ke akun tertentu. Hal ini membantu Account defense memproses pola aktivitas pengguna guna membangun model aktivitas untuk setiap akun agar dapat mendeteksi traffic yang tidak wajar dan melanggar dengan lebih baik.

Pilih ID akun yang stabil accountId yang tidak sering diubah oleh pengguna dan berikan ke penilaian dalam metode projects.assessments.create. ID akun yang stabil ini harus memiliki nilai yang sama untuk semua peristiwa yang terkait dengan pengguna yang sama. Anda dapat memberikan hal berikut sebagai ID akun:

ID pengguna

Jika setiap akun dapat dikaitkan secara unik dengan nama pengguna, alamat email, atau nomor telepon yang stabil, Anda dapat menggunakannya sebagai accountId. Saat Anda memberikan ID lintas situs tersebut (ID yang dapat digunakan kembali di seluruh situs), Fraud Defense menggunakan informasi ini untuk meningkatkan perlindungan bagi akun pengguna Anda berdasarkan model lintas situs dengan menandai ID akun yang melanggar dan menggunakan pengetahuan tentang pola penyalahgunaan lintas situs yang terkait dengan ID ini.

Atau, jika Anda memiliki ID pengguna internal yang secara unik terkait dengan setiap akun, Anda dapat memberikannya sebagai accountId.

Di-hash atau dienkripsi

Jika Anda tidak memiliki ID pengguna internal yang secara unik terkait dengan setiap akun, Anda dapat mengubah ID stabil apa pun menjadi ID akun spesifik per situs yang buram. ID ini masih diperlukan untuk pelindung akun Fraud Defense guna memahami pola aktivitas pengguna dan mendeteksi perilaku anomali, tetapi tidak dibagikan di situs lain.

Pilih ID akun yang stabil dan buat menjadi buram sebelum mengirimkannya ke Fraud Defense dengan menggunakan enkripsi atau hashing:

  • enkripsi (direkomendasikan): mengenkripsi ID akun menggunakan metode enkripsi deterministik yang menghasilkan ciphertext stabil. Untuk petunjuk mendetail, lihat mengenkripsi data secara deterministik. Jika memilih enkripsi simetris daripada hashing, Anda tidak perlu mempertahankan pemetaan antara ID pengguna dan ID pengguna buram yang sesuai. Mendekripsi ID buram yang ditampilkan oleh Fraud Defense untuk mengubahnya menjadi ID pengguna.

  • hashing: sebaiknya lakukan hashing pada ID akun menggunakan metode SHA256-HMAC dengan salt kustom pilihan Anda. Karena hash hanya bersifat satu arah, Anda harus menyimpan pemetaan antara hash yang dihasilkan dan ID pengguna Anda agar dapat memetakan ID akun yang di-hash yang ditampilkan kembali ke akun asli.

Selain memberikan ID akun yang stabil untuk semua permintaan terkait akun, Anda dapat memberikan ID akun tambahan, yang berpotensi tidak stabil, untuk beberapa permintaan tertentu. ID akun khusus konteks yang diberikan selain accountId membantu Account defense menganalisis aktivitas pengguna dengan lebih baik dan mendeteksi upaya pengambilalihan akun untuk menjaga keamanan akun pengguna Anda. Saat Anda memberikan ID tambahan, Google Cloud Fraud Defense menggunakan informasi ini untuk meningkatkan perlindungan bagi akun pengguna Anda berdasarkan model lintas situs dengan menandai ID akun yang melanggar dan menggunakan pengetahuan tentang pola penyalahgunaan lintas situs yang terkait dengan ID ini. Misalnya, Anda dapat memberikan hal berikut:

  • Nama pengguna, alamat email, atau nomor telepon yang digunakan sebagai nama login untuk permintaan login

  • Alamat email atau nomor telepon yang diverifikasi untuk permintaan autentikasi multi-faktor

  • Alamat email atau nomor telepon (utama atau sekunder) yang diberikan oleh pengguna selama permintaan pembaruan akun

  • Alamat email dan nomor telepon yang diberikan oleh pengguna selama permintaan pendaftaran

Tambahkan ID akun stabil yang dipilih ke parameter accountId dalam metode projects.assessments.create untuk semua permintaan terkait akun. Secara opsional, berikan ID akun tambahan untuk permintaan yang relevan menggunakan kolom userIds dalam penilaian.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • TOKEN: token yang ditampilkan dari panggilan grecaptcha.enterprise.execute()
  • KEY_ID: Kunci reCAPTCHA yang terkait dengan situs
  • ACCOUNT_ID: ID yang secara unik terkait dengan akun pengguna untuk akun pengguna ke situs Anda
  • EMAIL_ADDRESS: Opsional. Alamat email yang terkait dengan permintaan ini, jika ada
  • PHONE_NUMBER: Opsional. Nomor telepon yang terkait dengan permintaan ini, jika ada
  • USERNAME: Opsional. Nama pengguna yang terkait dengan permintaan ini, jika ada

Metode HTTP dan URL: 

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

Meminta isi JSON: 

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Anda akan melihat respons JSON seperti berikut:

{
  "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"]
  }
}

Contoh kode

Java

Untuk melakukan autentikasi ke Fraud Defense, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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;
  }
}

Menafsirkan keputusan risiko peristiwa pengguna yang penting

Saat Anda membuat penilaian dengan mengaktifkan Account defense, Account defense akan menampilkan accountDefenderAssessment sebagai bagian dari respons penilaian. Nilai accountDefenderAssessment membantu Anda menilai apakah aktivitas pengguna sah atau bersifat menipu. Metode ini juga menampilkan ID penilaian yang perlu Anda gunakan saat menganotasi peristiwa pengguna.

Contoh berikut adalah contoh respons 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"]
  }
}

Kolom accountDefenderAssessment dapat memiliki salah satu nilai berikut:

Nilai Deskripsi
SUSPICIOUS_LOGIN_ACTIVITY Menunjukkan bahwa permintaan tersebut memiliki risiko tinggi credential stuffing atau pengambilalihan akun.
SUSPICIOUS_ACCOUNT_CREATION Menunjukkan bahwa permintaan tersebut mewakili risiko tinggi pembuatan akun yang melanggar.
PROFILE_MATCH

Menunjukkan bahwa atribut pengguna cocok dengan atribut yang telah dilihat sebelumnya untuk pengguna tertentu ini. Nilai ini merupakan indikator bahwa pengguna ini menggunakan perangkat tepercaya yang sebelumnya digunakan untuk mengakses situs Anda.

PROFILE_MATCH hanya ditampilkan dalam skenario berikut:

  • Anda menggunakan Autentikasi multi-faktor (MFA) atau Autentikasi 2 langkah (2FA) dan Account defense menandai profil pengguna sebagai tepercaya setelah pengguna lulus verifikasi MFA atau 2FA.
  • Anda menganotasi penilaian sebagai LEGITIMATE atau PASSED_TWO_FACTOR dan Account defense akan menandai profil pengguna yang sesuai sebagai tepercaya.
RELATED_ACCOUNTS_NUMBER_HIGH Menunjukkan bahwa permintaan memiliki jumlah akun terkait yang tinggi. Hal ini tidak berarti bahwa akun tersebut buruk, tetapi mungkin memerlukan penyelidikan lebih lanjut.

Menganotasi peristiwa untuk menyesuaikan model spesifik per situs

Untuk memberikan informasi selengkapnya kepada Account defense dan meningkatkan model deteksi khusus situs, Anda harus menganotasi peristiwa yang Anda nilai dengan membuat penilaian.

Anda memberi anotasi pada penilaian dengan mengirimkan permintaan ke metode projects.assessments.annotate dengan ID penilaian. Dalam isi permintaan tersebut, Anda menyertakan label yang memberikan informasi tambahan tentang peristiwa yang dijelaskan dalam penilaian.

Untuk memberi anotasi pada penilaian, lakukan hal berikut:

  1. Tentukan informasi dan label yang akan ditambahkan dalam isi JSON permintaan, bergantung pada kasus penggunaan Anda.

    Tabel berikut mencantumkan label dan nilai yang dapat Anda gunakan untuk menganotasi peristiwa:

    Label Deskripsi Contoh permintaan
    reasons Wajib. Label untuk mendukung penilaian Anda.

    Berikan detail peristiwa real-time di label reasons dalam beberapa detik atau menit setelah peristiwa karena detail tersebut memengaruhi deteksi real-time.

    Untuk mengetahui daftar nilai yang mungkin, lihat nilai alasan.

    Contoh: Untuk mendeteksi pengambilalihan akun, beri anotasi jika sandi yang dimasukkan sudah benar dengan nilai CORRECT_PASSWORD atau INCORRECT_PASSWORD. Jika men-deploy MFA Anda sendiri, Anda dapat menambahkan nilai berikut: INITIATED_TWO_FACTOR, dan PASSED_TWO_FACTOR atau FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Opsional. Label untuk menunjukkan legitimasi penilaian.

    Berikan fakta tentang peristiwa login dan pendaftaran untuk memvalidasi atau memperbaiki penilaian risiko Anda di label annotation.

    Nilai yang mungkin: LEGITIMATE atau FRAUDULENT.

    Anda dapat mengirimkan informasi ini kapan saja atau sebagai bagian dari tugas batch. Namun, sebaiknya kirimkan informasi ini dalam beberapa detik atau menit setelah peristiwa karena informasi tersebut memengaruhi deteksi real-time.

    		 
          {
       "annotation": "LEGITIMATE"
      }
    accountId

    Opsional. Label untuk mengaitkan ID akun dengan peristiwa.

    Jika Anda membuat penilaian tanpa ID akun, gunakan label ini untuk memberikan ID akun peristiwa setiap kali tersedia.

    		 
      {
   "accountId": "ACCOUNT_ID"
  }

  2. Buat permintaan anotasi dengan label yang sesuai.

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • ASSESSMENT_ID: Nilai kolom name yang ditampilkan dari panggilan projects.assessments.create.
    • ANNOTATION: Opsional. Label untuk menunjukkan apakah penilaian tersebut sah atau bersifat menipu.
    • REASONS: Opsional. Alasan yang mendukung anotasi Anda. Untuk mengetahui daftar kemungkinan nilai, lihat nilai alasan.
    • ACCOUNT_ID: Opsional. ID yang secara unik terkait dengan akun pengguna di situs Anda.

    Untuk mengetahui informasi selengkapnya, lihat label untuk anotasi.

    Metode HTTP dan URL: 

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

    Meminta isi JSON: 

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

    Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

    curl

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

    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

    Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

    $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

    Anda akan menerima kode status berhasil (2xx) dan respons kosong.

Contoh kode

Java

Untuk melakukan autentikasi ke Fraud Defense, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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);
    }
  }
}

Menggunakan dan menafsirkan skor risiko pengambilalihan akun

Fitur skor risiko Pengambilalihan Akun (ATO) menambahkan skor risiko numerik dan penjelasan yang dapat dibaca manusia ke penilaian Account defense. Insight ini membantu Anda memahami penilaian dan menginformasikan tindakan atau keputusan Anda berikutnya.

Mendapatkan skor risiko

Untuk menerima skor risiko dan alasan penjelasan, kirim permintaan CreateAssessment dan sertakan event.userInfo.accountId dalam permintaan Anda.

Membaca skor risiko dan detailnya

Skor risiko dan alasan penjelasannya ada di objek accountDefenderAssessment.accountTakeoverVerdict dalam respons penilaian.

  • Penilaian risiko: accountDefenderAssessment.accountTakeoverVerdict.risk
  • Alasan risiko: accountDefenderAssessment.accountTakeoverVerdict.riskReasons
  • Alasan kepercayaan: accountDefenderAssessment.accountTakeoverVerdict.trustReasons

Cuplikan berikut menunjukkan contoh kolom dalam respons penilaian:

  "accountDefenderAssessment": {
    "labels": ["PROFILE_MATCH"],
    "accountTakeoverVerdict": {
      "risk": 0.249,
      "riskReasons": [{"reason": "CLIENT_ACCESSED_MANY_ACCOUNTS"}],
      "trustReasons": [{"reason": "PROFILE_MATCH"}, {"reason": "ACCOUNT_HISTORY_REPUTABLE"}]
    }
  }

Menafsirkan skor risiko ATO

Saat Anda menggunakan skor risiko, tetapkan nilai minimum untuk menentukan kapan harus mengambil tindakan perlindungan.

Gunakan skor risiko ATO sebagai alternatif untuk label SUSPICIOUS_LOGIN_ACTIVITY. Jangan gunakan skor risiko dan label untuk memicu penegakan pada penilaian yang sama. Anda dapat mengonfigurasi logika penerapan berdasarkan skor risiko yang melebihi batas atau berdasarkan keberadaan label. Umumnya, skor risiko menawarkan penilaian yang lebih terperinci.

Sebaiknya evaluasi performa penilaian risiko dengan nilai minimum yang sesuai pada traffic platform Anda sebelum menggunakannya untuk penegakan kebijakan.

Untuk menindaklanjuti skor risiko, terapkan pemeriksaan di backend Anda seperti yang ditunjukkan dalam cuplikan berikut:

if (assessment.accountDefenderAssessment.accountTakeoverVerdict.risk > YOUR_CHOSEN_THRESHOLD) {
  // Treat as suspicious
  // Implement protective actions
}

Nilai minimum penilaian risiko standar

Tabel berikut memberikan nilai minimum skor penilaian risiko standar dan Rasio Positif Palsu (FPR) yang diharapkan. Pilih nilai minimum berdasarkan FPR yang dapat diterima. Performa dapat bervariasi, jadi Anda mungkin perlu menyesuaikan nilai minimum berdasarkan performa yang diamati.

Toleransi risiko Nilai minimum yang direkomendasikan Rasio positif palsu maksimum
Rendah 0,5 4%
Sedang 0,7 1%
Tinggi 0,9 0,25%

Menafsirkan alasan penjelasan

Alasan penjelasan memberikan insight tentang faktor-faktor yang memengaruhi skor risiko. Gunakan alasan ini untuk menyempurnakan pengambilan keputusan Anda.

  • Alasan risiko: menunjukkan faktor yang terkait dengan risiko pengambilalihan akun yang lebih tinggi.
  • Alasan kepercayaan: menunjukkan faktor yang mengindikasikan legitimasi.

Alasan risiko dan kepercayaan dapat muncul untuk skor risiko tertentu.

Alasan Jenis Penafsiran
PROFILE_MATCH Kepercayaan Permintaan cocok dengan profil tepercaya yang terkait dengan akun ini. Label ini setara dengan label AccountDefenderLabel.PROFILE_MATCH.
ACCOUNT_HISTORY_REPUTABLE Kepercayaan Histori aktivitas akun memiliki reputasi baik. Kecil kemungkinan akun telah disusupi sebelumnya.
CLIENT_HISTORICAL_BOT_ACTIVITY Risiko Klien telah diamati mengirimkan traffic mirip bot ke situs ini sebelumnya. Alasan ini menggabungkan reputasi historis dan menunjukkan bahwa klien diketahui menggunakan bot, meskipun permintaan saat ini dibuat oleh manusia.
ACCOUNT_IN_LARGE_RELATED_GROUP Risiko Akun tersebut merupakan bagian dari grup besar akun terkait, yang menunjukkan bahwa akun tersebut mungkin merupakan bagian dari jaringan penipuan. Akun terkait diidentifikasi berdasarkan pola traffic dan karakteristik permintaan yang serupa.
CLIENT_ACCESSED_MANY_ACCOUNTS Risiko Klien telah diamati mengakses banyak akun di situs ini.
DISPOSABLE_EMAIL_DOMAIN Risiko Alamat email yang diberikan adalah milik penyedia domain email sementara dan sekali pakai (sekali pakai) yang diketahui atau dicurigai.

Menyesuaikan nilai minimum risiko pengambilalihan akun

Setelah mengevaluasi performa penilaian risiko pengambilalihan akun pada traffic, Anda mungkin perlu menyesuaikan nilai minimum untuk mencapai Rasio Positif Palsu (FPR) dan perolehan yang dapat diterima. Anda dapat menyesuaikan nilai minimum berdasarkan performa yang diamati atau menghitung nilai menengah untuk menargetkan FPR tertentu.

Menyesuaikan nilai minimum Anda

Jika FPR yang diamati terlalu tinggi, naikkan nilai minimum. Jika perolehan yang diamati terlalu rendah dan Anda dapat menoleransi FPR yang lebih tinggi, turunkan nilai minimum.

Menghitung nilai antara

Untuk memperkirakan FPR untuk nilai minimum di antara nilai standar, gunakan interpolasi linear. Contoh berikut menunjukkan cara menghitung FPR untuk nilai minimum 0,85:

FPR(T: 0.85) = (FPR(T: 0.8) + FPR(T: 0.9)) / 2 = (0.5% + 0.25%) / 2 = 0.375%

Untuk menemukan nilai minimum untuk FPR tertentu, lakukan interpolasi di antara nilai standar. Contoh berikut menunjukkan cara menemukan nilai minimum untuk FPR sebesar 5%:

Threshold = 0.4 + (0.5 − 0.4) × (8% − 5%) / (8% − 4%)
Threshold = 0.4 + 0.1 × (3 / 4)
Threshold = 0.4 + 0.075 = 0.475

Nilai minimum 0,475 diperkirakan akan menghasilkan FPR 5%.

Langkah berikutnya