Implement a CAPTCHA

The Advanced Identity Cloud/PingAM Login Widget supports the use of a CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart), which helps to prevent automated scripts from attempting to authenticate to your servers.

To use a CAPTCHA in the Advanced Identity Cloud/PingAM Login Widget, add a CAPTCHA node or reCAPTCHA Enterprise node to your authentication journey.

Supported CAPTCHA variants

Advanced Identity Cloud/PingAM Login Widget supports the following CAPTCHA variants:

CAPTCHA variant	Support	Node
hCaptcha	Active Invisible Passive / 99% Passive	CAPTCHA node
reCAPTCHA v2	Full, including Invisible reCAPTCHA.	CAPTCHA node
reCAPTCHA v3	Full	CAPTCHA node
reCAPTCHA Enterprise	Full, including invisible (score-based) mode.	reCAPTCHA Enterprise node

CAPTCHA variant

Support

Node

hCaptcha

Active

Invisible

Passive / 99% Passive

CAPTCHA node

reCAPTCHA v2

Full, including Invisible reCAPTCHA.

Full

Full, including invisible (score-based) mode.

reCAPTCHA Enterprise node

Visible and invisible CAPTCHA modes

CAPTCHA providers typically offer two rendering modes:

Visible (active) mode: The CAPTCHA renders a visible widget, usually a checkbox, inside the login form. The user must interact with it before they can submit the form.
Invisible mode: No visible widget appears in the login form. Instead, the CAPTCHA runs an automated risk assessment in the background when the page loads. If the provider’s scoring determines the request looks suspicious, it may surface a challenge popup for the user to complete. Otherwise, authentication proceeds without any visible interruption.

The Advanced Identity Cloud/PingAM Login Widget defaults to visible mode. To enable invisible mode, pass mode: 'invisible' in the captcha option when configuring the widget:

import { configure } from '@forgerock/login-widget';

await configure({
    serverConfig: {
        wellknown: 'https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration',
    },
    // ... other config options ...
    captcha: {
        mode: 'invisible', // 'visible' (default) | 'invisible'
    },
});

The mode value applies to whichever CAPTCHA provider is configured in your authentication journey node, for example hCaptcha, reCAPTCHA v2, or reCAPTCHA Enterprise.

When invisible mode is active and the CAPTCHA challenge fails or expires, the Advanced Identity Cloud/PingAM Login Widget displays an inline error alert prompting the user to try again.

Configure your app

The Advanced Identity Cloud/PingAM Login Widget automatically injects the CAPTCHA provider script into your page when it encounters a CAPTCHA callback. You do not need to add a <script> tag manually.

If you prefer to load the script yourself, for example to control when it loads relative to other resources, you can add it to the <head> of your page. The widget detects that the provider is already available and skips its own injection.

hCaptcha

<script src="https://js.hcaptcha.com/1/api.js" async defer></script>

reCAPTCHA v2

<script async src="https://www.google.com/recaptcha/api.js"></script>

reCAPTCHA v3

If pre-loading reCAPTCHA v3, append your site key as a render query parameter:

<script async src="https://www.google.com/recaptcha/api.js?render={reCAPTCHA_site_key}"></script>

You can add a recaptchaAction property with a custom value when calling the journey. That value tags the event in the reCAPTCHA console so that you can track different usage:

import { journey } from '@forgerock/login-widget';

const journeyEvents = journey();

journeyEvents.start({
    journey: 'reCAPTCHAv3journey',
    // ...any other journey config required...
    recaptchaAction: 'loginVIPArea', // optional; falls back to journey name
});

If you do not provide a recaptchaAction value, the Advanced Identity Cloud/PingAM Login Widget attempts to use the name of the journey instead, if available.

reCAPTCHA Enterprise

The Advanced Identity Cloud/PingAM Login Widget handles the ReCaptchaEnterpriseCallback automatically when the journey contains the reCAPTCHA Enterprise node.

No additional script setup is required beyond configuring the node in your authentication journey.

For invisible (score-based) Enterprise keys, also set captcha: { mode: 'invisible' } in your widget configuration. Learn more in Visible and invisible CAPTCHA modes.

You can add a recaptchaAction property with a custom value when calling the journey. That value tags the event in the reCAPTCHA Enterprise console so that you can track different usage:

import { journey } from '@forgerock/login-widget';

const journeyEvents = journey();

journeyEvents.start({
    journey: 'reCAPTCHAEnterpriseJourney',
    // ...any other journey config required...
    recaptchaAction: 'loginVIPArea', // falls back to journey name
});

For reCAPTCHA Enterprise, either recaptchaAction or journey must be provided for the CAPTCHA to execute.

Test a CAPTCHA

With your app configured, you can visit any journey that contains a CAPTCHA node or reCAPTCHA Enterprise node to test a CAPTCHA with the Advanced Identity Cloud/PingAM Login Widget.

For example, the following image shows how the Advanced Identity Cloud/PingAM Login Widget displays a reCAPTCHA v2 challenge, alongside a platform username and platform password nodes, all within a single page node:

Figure 1. Login Widget handling reCAPTCHA v2 in a page node

Troubleshooting

This section contains information on how to diagnose issues when using a CAPTCHA with the Advanced Identity Cloud/PingAM Login Widget.

Why does the reCAPTCHA display "ERROR for site owner: Invalid key type"?

Ensure the site key you have specified in the CAPTCHA node is configured for the version of reCAPTCHA type you want to use.

For example, the following image shows a configuration for v2 Tickbox:

When using a v2 site key, do not select ReCaptcha V3 Node in the CAPTCHA node configuration.

Why does the browser console display "Error: Invalid site key or not loaded in api.js"?

Ensure you have added the correct site key value as a render query parameter of the Google api.js script.

For example:

<script async src="https://www.google.com/recaptcha/api.js?render=1249672216234"></script>

Why does the reCAPTCHA display "Localhost is not in the list of supported domains for this site key."?

The localhost domain is blocked from working with reCAPTCHA by default.

You can add the domain to the site key configuration for testing purposes if required.

It can take several minutes for changes to the allowed domains to take effect.

For more information, refer to Google’s reCAPTCHA documentation.