Integrating reCAPTCHA Enterprise into a JavaScript app

PingOne Advanced Identity Cloud PingAM JavaScript

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

Prerequisites

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

Load Google’s reCAPTCHA Enterprise JavaScript API JavaScript file in the HEAD of your app. You’ll need to add your site key as a parameter when loading the script:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render={siteKey}"></script>
  ...
</head>

To learn more, refer to Install score-based keys on websites in the Google Cloud documentation.

You can get the URI to the JavaScript file, and site key value from the ReCaptchaEnterpriseCallback, if you want to dynamically load the reCAPTCHA script.

Use the callback.getApiUrl() and callback.getSiteKey() methods if you want to dynamically load the reCAPTCHA API.

// Handling 'ReCaptchaEnterpriseCallback'
const callback = step.getCallbackOfType(‘ReCaptchaEnterpriseCallback’)

// Get the URI to the reCAPTCHA JavaScript file from the callback
const apiUrl = callback.getApiUrl();

// Get the site key from the callback
const siteKey = callback.getSiteKey();

Retrieve a reCAPTCHA_Enterprise_Token. You’ll need to return this to the server when Handling the callback with the SDK.

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 Orchestration SDKs:

Return the reCAPTCHA_Enterprise_Token you obtained earlier as follows:

// Handling 'ReCaptchaEnterpriseCallback'
const callback = step.getCallbackOfType(‘ReCaptchaEnterpriseCallback’)

// Set provider on the callback
callback.setResult(reCAPTCHA_Enterprise_Token);

// Submit the current step and get the next one
step = await journeyClient.next(step);

Configuring the verification

You can configure the type of action being performed in the call to verify():

Configuring the call to verify() on JavaScript

// Handling 'ReCaptchaEnterpriseCallback'
const callback = step.getCallbackOfType(‘ReCaptchaEnterpriseCallback’)

// Set provider on the callback
callback.setAction("LOGIN");

// Set provider on the callback
callback.setResult(reCAPTCHA_Enterprise_Token);

// Submit the current step and get the next one
step = await journeyClient.next(step);

The available properties for the action value are as follows:

LOGIN: For login journeys
SIGNUP: For registration journeys

Or you can specify your own action, as a string value.

callback.setAction("PASSWORD_RESET")
callback.setAction("PAYMENT")
callback.setAction("ADD_TO_CART")

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 customize data for an assessment, use the setPayload() method:

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

Returning custom error codes

You can return a custom error to the node if required for your business logic:

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