This page describes how to use the Password defense feature of reCAPTCHA to detect password leaks and breached credentials to prevent account takeovers (ATOs) and credential stuffing attacks. With reCAPTCHA, 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
-
Verify that billing is enabled for your Google Cloud project .
reCAPTCHA requires billing to be linked and enabled on the project to use the Password defense 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
You can check if a set of credentials has been compromised by using cryptographic functions or by using the Docker container.
The Docker container is an open-source client that implements the secure multi-party computation that is needed to preserve end-user privacy and securely look up password leaks. For more information, see the GitHub Repo . The Docker container abstracts the complexity of implementing the cryptographic algorithms and simplifies the installation process. It also lets you host the container app in your infrastructure.
Cryptographic function
To check if a set of credentials has been compromised, use Password defense 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 provides Java and TypeScript libraries to assist with generating these fields:
-
To create password check verifications, create a
PasswordCheckVerifierobject.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
lookupHashPrefixandencryptedUserCredentialsHashcontain 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
());
Code sample
Node.js (TypeScript)
To learn about how to implement password leak detection by using Node.js (TypeScript), see the TypeScript code sample on GitHub .
Java
To authenticate to reCAPTCHA, set up Application Default Credentials. For more information, see Set up authentication for a local development environment .
