reCaptcha configuration for nFactor authentication

Citrix Gateway supports a new first class action ‘captchaAction’ that simplifies reCaptcha configuration. As reCaptcha is a first class action, it can be a factor of its own. You can inject reCaptcha anywhere in the nFactor flow.

Previously, you had to write custom WebAuth policies with changes to RfWeb UI as well. With the introduction of captchaAction, you do not have to modify the JavaScript.


If reCaptcha is used along with username or password fields in the schema, submit button is disabled until reCaptcha is met.

reCaptcha configuration

reCaptcha configuration involves two parts.

  1. Configuration on Google for registering reCaptcha.
  2. Configuration on Citrix ADC appliance to use reCaptcha as part of login flow.

reCaptcha configuration on Google

Register a domain for reCaptcha at

  1. When you navigate to this page, the following screen appears.

    localized image


    Use reCAPTCHA v2 only. Invisible reCAPTCHA is still in Beta.

  2. After a domain is registered, the “SiteKey” and “SecretKey” are displayed.

    localized image


    The “SiteKey” and “SecretKey” are grayed out for security reasons. “SecretKey” must be kept safe.

reCaptcha configuration on Citrix ADC appliance

reCaptcha configuration on Citrix ADC appliance can be divided into three parts:

  • Display reCaptcha screen
  • Post the reCaptcha response to Google server
  • LDAP configuration is second factor for user logon (optional)

Display reCaptcha screen

The login form customization is done through the SingleAuthCaptcha.xml loginschema. This customization is specified at authentication virtual server and is sent to UI for rendering the login form. The built-in loginschema, SingleAuthCaptcha.xml, is at /nsconfig/loginSchema/LoginSchema directory on the Citrix ADC appliance.


  • Based on your use case and different schemas, you can modify the existing schema. For instance if you need only reCaptcha factor (without username or password) or dual authentication with reCaptcha.
  • If any custom modifications are performed or the file is renamed, Citrix recommends copying all loginSchemas from /nsconfig/loginschema/LoginSchema directory to parent directory, /nsconfig/loginschema.

To configure display of reCaptcha 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 reCaptcha response to Google server

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

To verify reCaptcha 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

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 -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 reCaptcha, 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 Citrix Gateway appliance is used for access. Administrator must configure the following command if load balancing virtual server is required:

  • add lb vserver lbtest HTTP <IP> <Port> -authentication ON -authenticationHost – Resolves to authentication virtual server.

User validation of reCaptcha

Once you have configured all the steps mentioned in the previous sections, you must see the UI screenshots shown below.

  1. Once the authentication virtual server loads the login page, the logon screen is displayed. Log On is disabled until reCaptcha is complete.

    localized image

  2. Select I’m not a robot option. The reCaptcha widget is displayed.

    localized image

  3. You are navigated through series of reCaptcha 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.

    localized image


    • If reCaptcha is used with AD authentication, Submit button for credentials is disabled until reCaptcha is complete.
    • The reCaptcha happens in a factor of its own. Therefore, any subsequent validations like AD must happen in the ‘nextfactor’ of reCaptcha.
reCaptcha configuration for nFactor authentication