Ping SDKs

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:

token-vault
  1. The SDKs start or continue an authentication journey by visiting the /authorize endpoint

  2. The next step in the journey is the reCAPTCHA Enterprise node, so the journey returns the a ReCaptchaEnterpriseCallback to the client.

  3. The client uses the values in the callback to request a token from the reCAPTCHA server.

  4. The reCAPTCHA server returns a unique token for the transaction to the client.

  5. 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.

  6. The node submits the data collected on the client to the reCAPTCHA server for assessment.

  7. 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.

  8. 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.

Add the following to your build.gradle configuration file:

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

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:

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)
}
java

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)
}
json

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:

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

Returning custom error codes

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

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