This document shows you how to use Account defense to detect and prevent account-related fraudulent activities on mobile applications.
Fraud Defense helps you protect critical actions, such as login and checkout. However, there are many subtle forms of account abuse that can be detected by observing a specific user's behavior on a mobile application over a period of time. Account defense, a feature of Fraud Defense, helps in identifying these kinds of subtle abuse by creating a site-specific model for your mobile application to detect a trend of suspicious behavior or a change in activity. By using the site-specific model, Account defense helps you detect the following:
- Suspicious activities
- Accounts with similar behaviors
- Requests coming from devices that were marked as trusted for specific users
Based on the analysis of Account defense and the site-specific model, you can take the following actions:
- Restrict or disable fraudulent accounts.
- Prevent account takeover attempts.
- Mitigate the successful account takeovers.
- Grant access only to the requests coming from legitimate user accounts.
- Reduce friction for users logging in from one of their trusted devices.
Before you begin
- Account defense for mobile applications is accessible after triggering an automatic security review by adding a billing account to your project. Add a billing account to your project to onboard your mobile application to this feature.
- Prepare your environment for Google Cloud Fraud Defense.
- Create a score-based key.
Configure your mobile application for Account defense
Account defense requires a comprehensive understanding of account activities to enable effective detection. To start feeding account-related activities to Account defense, and to create and improve your site-specific model, do the following:
Integrate Fraud Defense with your mobile application.
- For Android apps, see Integrate Fraud Defense with Android apps.
- For iOS apps, see Integrate Fraud Defense with iOS apps.
- Report on critical user actions.
- Assess critical user events.
- Annotate user events to tune your site-specific model.
Report on critical user actions
To detect suspicious activity patterns and build a better model of
typical activity patterns on your site, Account defense needs the information about critical user actions.
For each action of your app that is protected using Fraud Defense, call the execute() method with RecaptchaAction. For more information about execute() and RecaptchaAction, see the following:
- Android:
execute()andRecaptchaAction. - iOS:
execute()andRecaptchaAction.
The reCAPTCHA library provides a built-in set of actions, and if necessary you can create custom actions.
The following table lists the action names that you can use when reporting the critical user actions.
| Action name | User initiated event or user action |
|---|---|
LOGIN |
Login to the mobile application. |
SIGNUP |
Sign up on the mobile application. |
Assess critical user events
When you call execute() on a user action, it generates a token. For the critical
user events, such as successful and failed logins, registrations, and actions of the logged-in
users, create an assessment to assess the results of the execute() call. The
assessment provides you a risk verdict, which you can use to make a decision about how to handle
potentially fraudulent activities. Some of the actions you can take are blocking suspicious
requests, challenging risky logins, and investigating accounts of interest.
Account defense requires you to provide a stable account identifier to make the assessment and to attribute user activity–such as login requests, logged-in requests, and signup requests–to a specific account. This helps Account defense process user activity patterns to build an activity model for each account to better detect anomalous and abusive traffic.
Choose a stable account identifier accountId that is not often changed by the user
and provide it to the assessment in the
projects.assessments.create method. This stable account identifier should have the
same value for all the events related to the same user. You can provide the following as the account
identifier:
User identifiers
If every account can be uniquely associated with a stable username, email address, or phone
number, you can use it as the accountId. When you provide such cross-site
identifiers (identifiers that can be reused across sites), Fraud Defense uses this
information to improve protection for your user accounts based on cross-site models by
flagging abusive account identifiers and using knowledge of cross-site abuse patterns related
to these identifiers.
Alternatively, if you have an internal user ID uniquely associated with each account, you can
provide it as the accountId.
Hashed or encrypted
If you do not have an internal user ID uniquely associated with each account, you can turn any stable identifier into an opaque, site-specific account identifier. This identifier is still needed for Fraud Defense account defender to understand user activity patterns and detect anomalous behaviour, but it is not shared across other sites.
Pick any stable account identifier and make it opaque before sending to Fraud Defense by using encryption or hashing:
encryption (recommended): encrypt the account identifier using a deterministic encryption method that produces a stable ciphertext. For detailed instructions, see encrypt data deterministically. When you choose symmetric encryption over hashing, you don't need to keep a mapping between your user identifiers and the corresponding opaque user identifiers. Decrypt the opaque identifiers that are returned by Fraud Defense to turn them into the user identifier.
hashing: we recommend hashing the account identifier using the SHA256-HMAC method with a custom salt of your choice. Because hashes are one-way only, you need to keep a mapping between the generated hashes and your user identifiers so that you can map the hashed account identifier that are returned back to the original accounts.
In addition to providing a stable account identifier for all the account-related requests, you
can provide additional account identifiers, potentially non-stable, for some specific requests.
Context-specific account identifiers provided in addition to the accountId help
Account defense better analyze user activity and detect account
takeover attempts to keep your user accounts safe. When you provide additional identifiers,
Google Cloud Fraud Defense uses this information to improve protection for your user accounts based on
cross-site models by flagging abusive account identifiers and using knowledge of cross-site abuse
patterns related to these identifiers. For example, you can provide the following:
The username, email address, or phone number that was used as a login handle for login requests
The email address or phone number that was verified for a multi-factor authentication request
An email address or phone number (primary or secondary) that was provided by the user during an account update request
The email addresses and phone numbers that are provided by the user during a registration request
Append the chosen stable account identifier to the accountId parameter in the
projects.assessments.create method for all the account-related requests. Optionally,
provide additional account identifiers for the relevant requests by using the userIds
field in the assessment.
Before using any of the request data, make the following replacements:
- PROJECT_ID: your Google Cloud project ID
- TOKEN: token returned from the
execute()call - KEY_ID: reCAPTCHA key associated with the app
- ACCOUNT_ID: the identifier that is uniquely associated with the user account for a user account to your app
- EMAIL_ADDRESS: Optional. An email address that is associated with this request, if any
- PHONE_NUMBER: Optional. A phone number that is associated with this request, if any
- USERNAME: Optional. A username that is associated with this request, if any
HTTP method and URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Request JSON body:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userInfo": {
"accountId": "ACCOUNT_ID",
"userIds": [
{
"email": "EMAIL_ADDRESS"
},
{
"phoneNumber": "PHONE_NUMBER"
},
{
"username": "USERNAME"
}
]
}
}
}
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:
{
"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"]
}
}
Code sample
Java
To authenticate to Fraud Defense, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.