This page describes how to use the password leak detection feature of reCAPTCHA Enterprise to 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
Make sure that billing is enabled for your Google Cloud 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 leaked credentials
To check if a set of credentials has been compromised, use password leak detection when creating assessments for actions such as logins, password changes, and password resets.
To check for password leaks and breached credentials, complete the following steps:
- Generate request parameters.
- Create an assessment to detect password leaks.
- Verify leaked credentials from an assessment.
- Interpret verdict and take actions.
Generate request parameters
Calculate the necessary request parameters by using the cryptographic functions required by the high-privacy protocol. reCAPTCHA Enterprise provides Java and TypeScript libraries to assist with generating these fields:
To create password check verifications, create a
PasswordCheckVerifier
object.PasswordCheckVerifier verifier = new PasswordCheckVerifier();
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();
Create an assessment by using the verification parameters.
byte[] lookupHashPrefix = verification.getLookupHashPrefix(); byte[] encryptedUserCredentialsHash = verification.getEncryptedUserCredentialsHash();
The byte arrays
lookupHashPrefix
andencryptedUserCredentialsHash
contain the parameters that are required to initiate a password checkAssessment
.
Create an assessment to detect password leaks
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 SHA-256 hash prefix
- ENCRYPTED_USER_CREDENTIALS_HASH: encrypted user credentials Scrypt 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 named request.json
,
and execute the following command:
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
Save the request body in a file named request.json
,
and execute the following command:
$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
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 leaked credentials from an assessment
From the assessment 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());
Interpret verdict and take actions
The assessment response shows if the credentials were leaked and provides you with information that you can use to take appropriate actions to protect your users.
The following table lists the recommended actions that you can take when a leaked password is detected:
Leaked password detected | Actions to protect your user |
---|---|
During sign-in |
|
During account creation or password reset |
|
If you aren't using an MFA provider on your site already, you can use the MFA capability of reCAPTCHA Enterprise.
Code sample
Java
To authenticate to reCAPTCHA Enterprise, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
To authenticate to reCAPTCHA Enterprise, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
Node.js (TypeScript)
What's next
- Learn about how to use multi-factor authentication (MFA)
- Learn about how to protect users accounts by using reCAPTCHA Enterprise Account Defender