Detect password leaks and breached credentials

reCAPTCHA Enterprise can detect password leaks and breached credentials to prevent account takeovers (ATOs) and credential stuffing attacks. With reCAPTCHA Enterprise, you can conduct regular audits of user credentials (passwords) as part of any assessment to ensure that they have not been leaked or breached. To perform these assessments, Google uses the Password Checkup feature.

Before you begin

  1. Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.

  2. Password leak detection is accessible after approval. Contact our sales team to onboard your site to this feature.

  3. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

    reCAPTCHA Enterprise requires billing to be linked and enabled on the project to use the password leak detection feature. You can enable billing by using either a credit card or an existing Google Cloud project billing ID. If you require assistance with billing, contact the Cloud Billing Support.

Check for breached and/or leaked credentials

To check if a set of credentials has been compromised, query the Password Checkup database during assessments for actions, such as logins and password changes or resets.

To use the password leak detection service and to determine whether there was a leak or not from the response, you must calculate the parameters by using the cryptographic functions required by the high-privacy protocol. To do this, reCAPTCHA Enterprise provides a Java library: java-recaptcha-password-check-helpers.

Generate the request parameters

  1. To create password check verifications, create a PasswordCheckVerifier object.

    PasswordCheckVerifier verifier = new PasswordCheckVerifier();
    
  2. To initiate a verification, call PasswordCheckVerifier#createVerification. This method uses the username and password to calculate the parameters to perform the password check.

    PasswordCheckVerification verification = verifier.createVerification("username", "password").get();
    
  3. Create an assessment by using the verification parameters.

    byte[] lookupHashPrefix = verification.getLookupHashPrefix();
    byte[] encryptedUserCredentialsHash = verification.getEncryptedUserCredentialsHash();
    

The byte arrays lookupHashPrefix and encryptedUserCredentialsHash contain the parameters that are required to initiate a password check Assessment.

API request

Use the projects.assessments.create method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID
  • LOOKUP_HASH_PREFIX: prefix of the username Scrypt hash hash prefix
  • ENCRYPTED_USER_CREDENTIALS_HASH: encrypted user credentials SHA-256 hash

HTTP method and URL:

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

Request JSON body:

{
  "private_password_leak_verification": {
    "lookup_hash_prefix": "LOOKUP_HASH_PREFIX"
    "encrypted_user_credentials_hash": "ENCRYPTED_USER_CREDENTIALS_HASH"
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default 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

You should receive a JSON response similar to the following:

{
  "name": "projects/698047609967/assessments/fb22000000000000",
  "score": 0,
  "reasons": [],
  "privatePasswordLeakVerification": {
    "lookupHashPrefix": "zoxZwA==",
    "encryptedUserCredentialsHash": "AyRihRcKaGLj/FA/r2uqQY/fzfTaDb/nEcIUMeD3Tygp",
    "reencryptedUserCredentialsHash": "Aw65yEbLM39ww1ridDEfx5VhkWo11tzn/R1B88Qqwr/+"
    "encryptedLeakMatchPrefixes": [
      "n/n5fvPD6rmQPFyb4xk=", "IVQqzXsbZenaibID6OI=", ..., "INeMMndrfnlf6osCVvs=",
      "MkIpxt2x4mtyBnRODu0=", "AqUyAUWzi+v7Kx03e6o="]
  }
}

Verify a password leak

From the CreateAssessment response extract the fields reEncryptedUserCredentials and encryptedLeakMatchPrefixes, and pass them to the verifier object to determine if the credentials are leaked or not.

PasswordCheckResult result = verifier.verify(verification,
  result.getReEncryptedUserCredentials(),
  result.getEncryptedLeakMatchPrefixes()
).get();

System.out.println("Credentials leaked: " + result.areCredentialsLeaked());