Integrate with Google reCAPTCHA Enterprise

Applies to:

ForgeRock SDK for Android
ForgeRock SDK for iOS
ForgeRock SDK for JavaScript

Google ReCAPTCHA Enterprise uses advanced risk analysis techniques to distinguish between humans and bots. reCAPTCHA Enterprise is useful when you want to detect automated attacks or threats against your website or mobile apps.

These threats typically originate from scripts, mobile emulators, bot software, or humans.

Google reCAPTCHA Enterprise offers enhanced detection compared to earlier versions, with more granular scores, reason codes for risky events, mobile app SDKs, password breach and leak detection, multi-factor authentication (MFA), and the ability to tune your site-specific model to protect enterprise businesses.

Understand how the SDKs work with Google reCAPTCHA Enterprise

The following diagram outlines the flow of information between the client that is using the Ping SDKs, the reCAPTCHA Enterprise node in your journey, and the Google reCAPTCHA servers:

The SDKs start or continue an authentication journey by visiting the /authorize endpoint
The next step in the journey is the reCAPTCHA Enterprise node, so the journey returns the a ReCaptchaEnterpriseCallback to the client.
The client uses the values in the callback to request a token from the reCAPTCHA server.
The reCAPTCHA server returns a unique token for the transaction to the client.
The client adds the token to the callback and returns it to the node.

You can also add custom data to the payload that forms the assessment. See Customizing the assessment payload.
The node submits the data collected on the client to the reCAPTCHA server for assessment.

The reCAPTCHA server returns the response to the request to the node.

You can enable to the Store reCAPTCHA assessment JSON option in the node to save this data in the state for additional processing later in the journey.

The node stores the JSON in a variable named CaptchaEnterpriseNode.ASSESSMENT_RESULT.

The node verifies the response against the Score threshold you configure in the node, and continues the journey along the relevant outcome, true or false.

The client handles the next node as the journey continues.

Set up a journey for reCAPTCHA Enterprise

To enable reCAPTCHA Enterprise, add the reCAPTCHA Enterprise node to a journey.

This node returns a ReCaptchaEnterpriseCallback callback that the SDKs can handle to perform the reCAPTCHA Enterprise assessment.

Prepare your app for reCAPTCHA Enterprise

To add support for reCAPTCHA Enterprise to your apps, complete the following prerequisite tasks.

Android
iOS
JavaScript

Add the following to your build.gradle configuration file:

implementation("com.google.android.recaptcha:recaptcha:18.x.x")

You can add the dependencies using Cocoapods or Swift Package Manager (SPM).

View instructions for Cocoapods

If you do not already have CocoaPods, install the latest version.
If you do not already have a Podfile, in a terminal window, run the following command to create a new Podfile:
```
pod init
```
Add the following lines to your Podfile:
```
pod 'FRCaptchaEnterprise'
```
Run the following command to install pods:
```
pod install
```

View instructions for Swift Package Manager

With your project open in Xcode, select File > Add Package Dependencies.
In the search bar, enter the ForgeRock SDK for iOS repository URL: https://github.com/ForgeRock/forgerock-ios-sdk.
Select the forgerock-ios-sdk package, and then click Add Package.
In the Choose Package Products dialog, set the Add to Target field for the FRCaptchaEnterprise library top be the name of your project.
Click Add Package.

In your project, import the library:

// Import the reCAPTCHA Enterprise library
import FRCaptchaEnterprise

In a JavaScript app you must complete the following steps before using reCAPTCHA Enterprise:

Load the reCAPTCHA Enterprise JavaScript.

To learn more, refer to Install score-based keys on websites in the Google Cloud documentation.
Obtain a reCAPTCHA Enterprise token.

To learn more, refer to Retrieve a token in the Google Cloud documentation.

Handling the callback with the SDK

Use code similar to the following to handle the ReCaptchaEnterpriseCallback in your client-side code using the Ping SDKs:

Android
iOS
JavaScript

ReCaptchaEnterpriseCallback callback;
try {
  callback.execute(application = application)
}
catch (e: Exception) {
  if(e is RecaptchaException) {
    Logger.error(
      "RecaptchaException",
      "${e.errorCode}:${e.message}"
    )
  }
  Logger.error("RecaptchaException", e.message)
}

var captcha: ReCaptchaEnterpriseCallback?
if #available(iOS 13.0, *) {
  Task {
    do {
      try await captcha.execute(action: "login")
    }
    catch let error as RecaptchaError {
      // Handle errors
    }
  }
}

Return the reCAPTCHA_Enterprise_Token you obtained earlier in the callback as follows:

const callback = step.getCallbackOfType<forgerock.ReCaptchaEnterpriseCallback>(
  forgerock.CallbackType.ReCaptchaEnterpriseCallback,
) as forgerock.ReCaptchaEnterpriseCallback;

callback.setResult(reCAPTCHA_Enterprise_Token);

return forgerock.FRAuth.next(step);

Customizing the assessment payload

You can add additional data to customize the payload that the server sends to the Google reCAPTCHA Enterprise for assessment.

Add data to the payload to leverage additional functionality provided by reCAPTCHA Enterprise.

The JSON format the payload expects is as follows:

{
  "token": string,
  "siteKey": string,
  "userAgent": string,
  "userIpAddress": string,
  "expectedAction": string,
  "hashedAccountId": string,
  "express": boolean,
  "requestedUri": string,
  "wafTokenAssessment": boolean,
  "ja3": string,
  "headers": [
    string
  ],
  "firewallPolicyEvaluation": boolean,
  "transactionData": {
    object (TransactionData)
  },
  "userInfo": {
    object (UserInfo)
  },
  "fraudPrevention": enum (FraudPrevention)
}

By default, the SDK or the node itself populates the following fields:

token
siteKey
userAgent
userIpAddress
expectedAction

You can however also override these values if it suits your use case.

You can add custom payload data as part of an authentication journey that includes the reCAPTCHA Enterprise node. Custom data in the journey overrides any custom data added by the client.

To learn more about the payload, refer to Project Assessments - Event in the Google Developer documentation.

To add custom data for an assessment, use the setPayload() method:

Android
iOS
JavaScript

// Optional payload values for customization
callback.setPayload(
    JSONObject().put("firewallPolicyEvaluation",false)
)

// Optional payload values for customization
callback.setPayload([
  "firewallPolicyEvaluation", false
])

// Optional payload values for customization
callback.setPayload({
  "firewallPolicyEvaluation": false
});

Returning custom error codes

You can return a custom error code to the node, which can then continue the journey based on the values:

Android
iOS
JavaScript

// Optional custom error code
callback.setClientError("custom_client_error")

// Optional custom error code
callback.setClientError("custom_client_error")

// Optional custom error code
callback.setClientError('custom_client_error');