Advanced Identity Cloud

reCAPTCHA Enterprise node

The reCAPTCHA Enterprise node adds Google reCAPTCHA Enterprise support to your journeys.

Google reCAPTCHA Enterprise offers improvements over previous versions, including more granular scores, reason codes for events deemed higher risk, Web Application Firewall (WAF) support, and native support for Android and iOS.

Compatibility

Product Compatible?

Advanced Identity Cloud

Yes 1

PingAM (self-managed)

Yes

Ping Identity Platform (self-managed)

Yes

1 Currently available only in the rapid release channel.

This node only supports Google reCAPTCHA Enterprise.

For reCAPTCHA v2 and v3 support, and hCaptcha support, use the CAPTCHA node.

Inputs

This node reads an optional CaptchaEnterpriseNode.PAYLOAD variable from shared state.

Use this variable to customize the payload the node sends to the Google reCAPTCHA Enterprise server for assessment.

You can set the value by using a Set State node, or by using a Scripted Decision node, using a script similar to the following:

var username = nodeState.get("username");
var customPayload =
  JSON.parse(`{"userInfo": {"accountId": "${username}"}}`);
sharedState.put("CaptchaEnterpriseNode.PAYLOAD", customPayload);
outcome = "true";

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

Dependencies

You need to sign up for access to the reCAPTCHA API to get the API key pair required to configure the node.

Configuration

Property Usage

Google Cloud project ID

The ID of the project that has Google reCAPTCHA enabled.

You can get the ID of your project in the Google Cloud console.

For example, my-project-65746-07969469388.

reCAPTCHA Site Key (required)

The ID of the reCAPTCHA key you created in the Google Cloud console.

The key can be for any platform type, Website, Android app, or iOS app.

Sometimes referred to as a key ID in the Google Cloud console and documentation.

reCAPTCHA API key secret identifier

An identifier used to create a secret label for mapping to your Google reCAPTCHA API key in a secret store.

Get or create your API key from the Google Cloud Console under APIs and Services > Credentials.

The secret label takes the form am.authentication.nodes.captchaEnterprise.identifier.secret where identifier is the value of reCAPTCHA API key secret identifier.

The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

Score Threshold

The score threshold for determining if a user is likely to be a real person.

reCAPTCHA scores are between 0.0 and 1.0, with higher scores indicating higher confidence that the user is a real person.

If the returned score is equal to or greater than the threshold the journey continues along the true outcome path.

To learn more, refer to Interpret scores in the Google documentation.

Store reCAPTCHA assessment JSON

Stores the assessment response JSON for future reference within the journey.

The node stores the JSON response in the CaptchaEnterpriseNode.ASSESSMENT_RESULT variable.

Store reCAPTCHA error messages

Stores the error messages for future reference within the journey.

The node stores the error messages in the CaptchaEnterpriseNode.FAILURE variable.

The error consists of an error code and description of the error.

View the possible error codes

  • INVALID_TOKEN

  • INVALID_PROJECT_ID

  • CLIENT_ERROR

  • INVALID_SECRET_KEY

  • VALIDATION_ERROR

  • API_ERROR

  • IO_ERROR

  • UNKNOWN

reCAPTCHA CSS class

A CSS class to apply to the HTML elements reCAPTCHA adds to JavaScript apps.

The default is g-recaptcha.

reCAPTCHA Verification URL

The URL to send the reCAPTCHA to for verification.

Only change this if Google updates the URL used for reCAPTCHA verifications.

The default is https://recaptchaenterprise.googleapis.com/v1.

JavaScript reCAPTCHA API URL

The URL of the JavaScript file containing the reCAPTCHA API.

Only change this if Google releases a new version of the JavaScript reCAPTCHA API.

The default is https://www.google.com/recaptcha/enterprise.js.

Outputs

If you enable the Store reCAPTCHA assessment JSON property, the node outputs the reCAPTCHA assessment response JSON in a state variable named CaptchaEnterpriseNode.ASSESSMENT_RESULT.

If you enable the Store reCAPTCHA error messages property, the node outputs the error response JSON in a state variable named CaptchaEnterpriseNode.FAILURE.

Outcomes

True

The reCAPTCHA response was successfully verified.

False

The reCAPTCHA response wasn’t verified or failed verification.

Example

The following journey uses a Page node and a Data Store Decision node to collect and verify the credentials and a CAPTCHA response:

The reCAPTCHA Enterprise node in context

This example uses the following nodes:

Copyright © 2010-2024 ForgeRock, all rights reserved.