Authentication nodes

CAPTCHA node

The CAPTCHA node adds CAPTCHA support by verifying the response token received from the CAPTCHA provider and creating a callback for the UI to interact with.

The node supports the following CAPTCHA providers:

  • Google reCAPTCHA v2 and v3

  • hCaptcha

  • FriendlyCaptcha v1 and v2 (available from v2.0 of the node)

By default, the node is configured for Google’s reCAPTCHA v2.

  • This node doesn’t support hCaptcha’s passive or invisible mode.

  • For Google reCAPTCHA Enterprise support, use the reCAPTCHA Enterprise node.

  • Use a v3.0 or later Page node when including a CAPTCHA node in the same page as a node that has validation enabled, such as the Platform Password node.

    The v3.0 Page node ensures that validateOnly requests are only processed for the node or nodes that own the validated callback. This prevents the CAPTCHA token from being reused during real-time validation and avoids final submission failures.

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 CAPTCHA node in context

This example uses the following nodes:

  • The Page node prompts the user to input their username and password:

    • The Platform Username node collects the username and stores it in the shared state.

    • The Platform Password node collects the password and stores it in the shared state.

    • The CAPTCHA node collects and verifies the CAPTCHA response.

  • The Data Store Decision node uses the username and password to determine whether authentication is successful.

Availability

Product Available?

PingOne Advanced Identity Cloud

Yes

PingAM (self-managed)

Yes

Ping Advanced Identity Software (self-managed)

Yes

Inputs

None. This node doesn’t read shared state data.

Dependencies

The node requires the site key and secret key from your CAPTCHA provider to verify the CAPTCHA response.

Before configuring the node, sign up with your CAPTCHA provider to get these details:

Configuration

Property Usage Availability

CAPTCHA Site Key (required)

The CAPTCHA site key supplied by the CAPTCHA provider when you sign up for access to the API.

All node versions

CAPTCHA Secret Key

The CAPTCHA secret key supplied by the CAPTCHA provider when you sign up for access to the API.

This property is deprecated. Use the CAPTCHA Secret Label Identifier instead.

If you set a CAPTCHA Secret Label Identifier, this secret key is ignored.

All node versions

CAPTCHA Secret Label Identifier

An identifier used to create a secret label for mapping to the CAPTCHA secret key in a secret store.

Advanced Identity Cloud uses this identifier to create a specific secret label for this node. The secret label takes the form am.authentication.nodes.captcha.identifier.secret where identifier is the value of CAPTCHA Secret Label 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.

All node versions

CAPTCHA Verification URL

The URL used to verify the CAPTCHA submission.

Possible values by provider depend on the node version:

  • v2.0

  • v1.0

Google reCAPTCHA v2 and v3

https://www.google.com/recaptcha/api/siteverify

hCaptcha

https://hcaptcha.com/siteverify

FriendlyCaptcha v1

https://api.friendlycaptcha.com/api/v1/siteverify

FriendlyCaptcha v2

https://global.frcapi.com/api/v2/captcha/siteverify

Google reCAPTCHA v2 and v3

https://www.google.com/recaptcha/api/siteverify

hCaptcha

https://hcaptcha.com/siteverify

Default: https://www.google.com/recaptcha/api/siteverify

All node versions

CAPTCHA API URL (required)

The URL of the JavaScript script that loads the CAPTCHA widget.

Possible values by provider depend on the node version:

  • v2.0

  • v1.0

Google reCAPTCHA v2 and v3

https://www.google.com/recaptcha/api.js

hCaptcha

https://hcaptcha.com/1/api.js

FriendlyCaptcha v1

https://cdn.jsdelivr.net/npm/friendly-challenge@version/widget.min.js

FriendlyCaptcha v2

https://cdn.jsdelivr.net/npm/@friendlycaptcha/sdk@version/site.min.js

Google reCAPTCHA v2 and v3

https://www.google.com/recaptcha/api.js

hCaptcha

https://hcaptcha.com/1/api.js

Default: https://www.google.com/recaptcha/api.js

All node versions

Class of CAPTCHA HTML Element

The class of the HTML element required by the CAPTCHA widget.

Possible values by provider depend on the node version:

  • v2.0

  • v1.0

Google reCAPTCHA v2 and v3

g-recaptcha

hCaptcha

h-captcha

FriendlyCaptcha v1 and v2

frc-captcha

Google reCAPTCHA v2 and v3

g-recaptcha

hCaptcha

h-captcha

Default: g-recaptcha

All node versions

ReCaptcha V3 node

This property only applies to Google reCAPTCHA. When enabled, all interactive v2 elements are removed from the page and replaced with the invisible v3 element. Only enable this property if you’re using Google reCAPTCHA v3.

Default: Not enabled

All node versions

Score Threshold

This property only applies to Google reCAPTCHA v3 and hCaptcha. These providers return a score for each request based on observed interaction with your site. The threshold you set here determines whether to allow or deny access based on that score.

A score of 1.0 is likely a good interaction and a score of 0.0 is likely a bot. Start with a threshold of 0.5.

Scores in a staging environment or a newly deployed production environment might not be accurate, because the CAPTCHA provider needs real site traffic to calibrate.

Learn more about score thresholds in the Google documentation.

Default: 0.0

All node versions

Disable submission until verified

When selected, form submission is disabled until CAPTCHA verification succeeds.

Default: Enabled

All node versions

Verification Request Parameter Name

The name of the request parameter that contains the user’s CAPTCHA response.

Possible values by provider are:

Google reCAPTCHA v2 and v3

response

hCaptcha

response

FriendlyCaptcha v1

solution

FriendlyCaptcha v2

response

Default: response

v2.0

Use API Key Header

Controls how the node sends the API key to the CAPTCHA verification endpoint.

By default, the key is sent as a secret form field. This method is used by Google reCAPTCHA v2 and v3, hCaptcha, and FriendlyCaptcha v1.

Enable this property to send the key in an X-API-Key HTTP header, as required by FriendlyCaptcha v2.

Default: Not enabled

v2.0

Load Widget Script As Module

Controls how the CAPTCHA widget script is loaded.

By default, the script is loaded as a classic JavaScript file. This method is used by Google reCAPTCHA v2 and v3, hCaptcha, and FriendlyCaptcha v1.

Enable this property to load the script as an ES module (type="module"), as required by FriendlyCaptcha v2.

Default: Not enabled

v2.0

Outputs

This node doesn’t change the shared state.

Callbacks

The node sends a ReCaptchaCallback, which the client uses to render the CAPTCHA widget and collect the user’s response.

Outcomes

True

The CAPTCHA response was successfully verified.

False

The CAPTCHA response wasn’t verified or failed verification.

Errors

This node can throw exceptions with the following messages:

  • CAPTCHA response required for verification

  • Unable to verify CAPTCHA response

  • Unable to retrieve state from token response

  • No secret key found

Changelog

Version Changes

2.0

Adds support for FriendlyCaptcha, which is a privacy-focused CAPTCHA provider.

Adds the following new configuration options to support both v1 and v2 of FriendlyCaptcha:

  • Verification Request Parameter Name

  • Use API Key Header

  • Load Widget Script As Module