The CAPTCHA widgets can protect your Apereo CAS deployment from bots, spam, and other forms of automated abuse. In this tutorial, we will briefly review the configuration steps required to turn on a CAPTCHA integration backed by Google reCAPTCHA, and we will also take a look different ways to activate CAPTCHA per applications and dedicated policies.

Our starting position is as follows:

• CAS 6.5.x
• Java 11
• CAS WAR Overlay

Google reCAPTCHA

Once the required extension module is included in the CAS WAR Overlay, the following settings are required to make the integration work:

cas.google-recaptcha.site-key=...
cas.google-recaptcha.secret=...

cas.google-recaptcha.verify-url=https://www.google.com/recaptcha/api/siteverify
cas.google-recaptcha.version=GOOGLE_RECAPTCHA_V2
cas.google-recaptcha.enabled=true

The site-key and the secret are settings that should be given to you by Google. All other HTML/Javascript changes are automatically handled and provided by CAS. With such settings configured, you should be able to see the following when you next deploy and run CAS:

Note that the above settings enable Google reCAPTCHA v2. Support for Google reCAPTCHA v3 is also available if you were to switch the version to use GOOGLE_RECAPTCHA_V3 instead.

Application Policies

The previous configuration does not specify any particular rules and conditions for CAPTCHA activation, which means by default all requests qualify and must pass through CAPTCHA. It is of course possible to exclude certain applications from CAPTCHA activation and validation rules, or disable CAPTCHA globally and only enforce validation rules for specific eligible applications.

Let’s consider a scenario where we would disable CAPTCHA globally first:

cas.google-recaptcha.enabled=false

…and instead, we design a policy such that all applications whose request URL begins with https://secure would be asked to pass through CAPTCHA:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "^https://secure.+",
  "name" : "Service",
  "id" : 1,
  "properties" : {
    "@class" : "java.util.HashMap",
    "captchaEnabled" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "true" ] ]
    }
  }
}

We could also take this one step further and narrow down the list of qualifying applications to those requests where the client remote IP address matches a specific regular expression pattern. For example, a practica use case might be that CAPTCHA should not be activated if the user is on a trusted private network or VPN:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "^https://secure.+",
  "name" : "Service",
  "id" : 1,
  "properties" : {
    "@class" : "java.util.HashMap",
    "captchaEnabled" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "true" ] ]
    },
    "captchaIPAddressPattern" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "192.168.+", "5.33.+" ] ]
    }
  }
}

Need Help?

If you have questions about the contents and the topic of this blog post, or if you need additional guidance and support, feel free to send us a note and ask about consulting and support services.

So…

I hope this review was of some help to you and I am sure that both this post as well as the functionality it attempts to explain can be improved in any number of ways. Please feel free to engage and contribute as best as you can.

Happy Coding,

Misagh Moayyed