re-Captcha configuration for nFactor authentication

Last published : Sep 22, 2026
NetScaler Gateway supports a new first-class action captchaAction that simplifies re-Captcha configuration. As re-Captcha is a first-class action, it can be a factor of its own. You can inject re-Captcha anywhere in the nFactor flow.
Previously, you had to write custom WebAuth policies with changes to the RfWebUI as well. With the introduction of captchaAction, you do not have to modify the JavaScript.
Important:
If re-Captcha is used along with the user name or password fields in the schema, the Submit button is disabled until re-Captcha is met.

re-Captcha configuration

re-Captcha configuration involves two parts.
  1. Configuration on Google for registering re-Captcha.
  2. Configuration on NetScaler appliance to use re-Captcha as part of login flow.

re-Captcha configuration on Google

Register a domain for re-Captcha at <https://www.google.com/recaptcha/admin#llist>.
  1. When you navigate to this page, the following screen appears.
    Register a site
    Note
    Use reCAPTCHA v2 only. Invisible re-Captcha is still in preview.
  2. After a domain is registered, the “SiteKey” and “SecretKey” are displayed.
    Site key and secret key
    Note
    The “SiteKey” and “SecretKey” are grayed out for security reasons. “SecretKey” must be kept safe.

re-Captcha configuration on a NetScaler appliance

The re-Captcha configuration on the NetScaler appliance can be divided into three parts:
  • Display re-Captcha screen
  • Post the re-Captcha response to Google server
  • LDAP configuration is second factor for user logon (optional)

Display re-Captcha screen

The login form customization is done through the SingleAuthCaptcha.xml login schema. This customization is specified at authentication virtual server and is sent to UI for rendering the login form. The built-in login schema, SingleAuthCaptcha.xml, is at the /nsconfig/loginSchema/LoginSchema directory on the NetScaler appliance.
Important
  • The SingleAuthCaptcha.xml login schema can be used when LDAP is configured as the first factor.
  • Based on your use case and different schemas, you can modify the existing schema. For instance if you need only re-Captcha factor (without user name or password) or dual authentication with re-Captcha.
  • If any custom modifications are done or the file is renamed, Citrix recommends copying all loginSchemas from the /nsconfig/loginschema/LoginSchema directory to the parent directory, /nsconfig/loginschema.

To configure display of re-Captcha using CLI

add authentication loginSchema singleauthcaptcha -authenticationSchema /nsconfig/loginschema/SingleAuthCaptcha.xml

add authentication loginSchemaPolicy singleauthcaptcha -rule true -action singleauthcaptcha

add authentication vserver auth SSL <IP> <Port>

add ssl certkey vserver-cert -cert <path-to-cert-file> -key <path-to-key-file>

bind ssl vserver auth -certkey vserver-cert

bind authentication vserver auth -policy singleauthcaptcha -priority 5 -gotoPriorityExpression END

Post the re-Captcha response to Google server

After you have configured the re-Captcha that must be displayed to the users, the admins add the configuration to the Google server to verify the re-Captcha response from the browser.

To verify re-Captcha response from the browser

add authentication captchaAction myrecaptcha -sitekey <sitekey-copied-from-google> -secretkey <secretkey-from-google>

add authentication policy myrecaptcha -rule true -action myrecaptcha

bind authentication vserver auth -policy myrecaptcha -priority 1
NetScaler contacts https://www.google.com/recaptcha/api/siteverify to validate the Captcha information. So, ensure that the site is reachable from NetScaler.
To verify if the Google site is reachable, run the script curl -vvv https://www.google.com/recaptcha/api/siteverify.
The following commands are required to configure if AD authentication is desired. Else, you can ignore this step.
add authentication ldapAction ldap-new -serverIP x.x.x.x -serverPort 636 -ldapBase "cn=users,dc=aaatm,dc=com" -ldapBindDn adminuser@aaatm.com -ldapBindDnPassword <password> -encrypted -encryptmethod ENCMTHD_3 -ldapLoginName sAMAccountName -groupAttrName memberof -subAttributeName CN -secType SSL -passwdChange ENABLED -defaultAuthenticationGroup ldapGroup

add authenticationpolicy ldap-new -rule true -action ldap-new

LDAP configuration is second factor for user logon (optional)

The LDAP authentication happens after re-Captcha, you add it to the second factor.
add authentication policylabel second-factor

bind authentication policylabel second-factor -policy ldap-new -priority 10

bind authentication vserver auth -policy myrecaptcha -priority 1 -nextFactor second-factor
Administrator needs to add appropriate virtual servers depending on whether load balancing virtual server or NetScaler Gateway appliance is used for access. Administrator must configure the following command if a load balancing virtual server is required:
add lb vserver lbtest HTTP <IP> <Port> -authentication ON -authenticationHost nssp.aaatm.com
**nssp.aaatm.com** – Resolves to authentication virtual server.

User validation of re-Captcha

Once you have configured all the steps mentioned in the previous sections, you must see the following UI.
  1. Once the authentication virtual server loads the login page, the logon screen is displayed. Log On is disabled until re-Captcha is complete.
    Enter credentials
  2. Select I’m not a robot option. The re-Captcha widget is displayed.
    Robot option
  3. You are navigated through a series of re-Captcha images, before the completion page is displayed.
  4. Enter the AD credentials, select the I'm not a robot check box and click Log On. If authentication succeeds, you are redirected to the desired resource.
    Series of images
    Notes:
    • If re-Captcha is used with AD authentication, the Submit button for credentials is disabled until re-Captcha is complete.
    • The re-Captcha happens in a factor of its own. Therefore, any subsequent validations like AD must happen in the nextfactor of re-Captcha.