Apereo CAS - Test-Driving Feature Modules

This blog is managed and hosted on GitHub. If you wish to update the contents of this post or if you have found an inaccuracy and wish to make corrections, we recommend that you please submit a pull request to this repository.


Following up on my previous blog post on changing CAS source code in an overlay, in this exercise we are going to more or less repeat the same experience except that this time, we will be addressing the changes and workload from the perspective of the CAS codebase. This quick walkthrough effectively aims for the following objectives:

  • A quick development environment setup using IntelliJ IDEA.
  • Building and running the CAS web application using Gradle.
  • Changing feature modules and testing out behavior.
  • Stepping into the code using a debugger.

Development Environment

Follow the instructions posted here to obtain the CAS source code. Remember to indicate the relevant branch in the commands indicated to obtain the right source code for the CAS version at hand. In this tutorial and just like before, the branch to use would be 5.2.x.

To understand what branches are available, see this link. Your CAS version is closely tied to the branches listed in the codebase. For example, if you are deploying CAS 5.1.8, then the relevant branch to check out would be 5.1.x. Remember that branches always contain the most recent changeset and version of the release line. You might be deploying 5.1.8 while the 5.1.x might be marching towards 5.1.10. This requires that you first upgrade to the latest available patch release for the CAS version at hand and if the problem or use case continues to manifest, you can then check out the appropriate source branch and get fancy [1].

Keep Up
It is STRONGLY recommended that you keep up with the patch releases as they come out. Test early and have the environment on hand for when the time comes to dabble into the source. Postponing patch upgrades in the interest of time will eventually depreciate your lifespan.

To set up the project in IntelliJ IDEA, it might be preferable to run ./gradlew idea at the root of the project. This will attempt to generate the needed project files beforehand, allowing the development environment setup to proceed without many delays. Note that similar tasks are available for eclipse, etc.

Running CAS

The CAS web application itself can be started from the command-prompt using an embedded Apache Tomcat container. In fact, this process is no different than deploying CAS using the same embedded Apache Tomcat container which means you will need to follow the instructions posted here in the way that certificates and other configurations are needed in /etc/cas/config, etc to ensure CAS can function as you need it. All features modules and behavior that would be stuffed into the web application artifact continue to read settings from the same location, as they would be when activated from an overlay. The process is exactly the same.

I use the following alias in my bash profile to spin up CAS using an embedded Apache Tomcat container. You might want to do the same thing, or create the equivalent script for other operating systems to reduce time and keystrokes:

alias bc='clear; cd ~/Workspace/cas/webapp/cas-server-webapp-tomcat; \
    ../../gradlew build install bootRun --configure-on-demand --build-cache --parallel \
    -x test -x javadoc -x check -DenableRemoteDebugging=true --stacktrace \
    -DskipNestedConfigMetadataGen=true -DskipGradleLint=true -DskipSass=true \
    -DskipNodeModulesCleanUp=true -DskipNpmCache=true -DskipNpmLint=true'

Then, I simply execute the following in the terminal:

> bc

To understand the meaning and function behind various command-line arguments, please see instructions posted here. You may optionally decide to tweak each setting if you are interested in a particular build variant, such as generating javadocs, running tests, etc. One particular flag of interest is the addition of enableRemoteDebugging, which allows you, later on, to connect a remote debugger to CAS on a specific port (i.e. 5000) and step into the code.

Bootiful CAS
At this time, the availability of the bootRun task running from inside IntelliJ IDEA is not possible.

Testing Modules

Per instructions posted here, the inclusion of a particular build module in the build.gradle of the CAS web application should allow the build process to automatically allow the module to be packaged and become available. Since the CAS web application we are running is supported by Apache Tomcat, the reference to the CAS reCAPTCHA module can be included right there.

Alternatively, you may also include the reference in the webapp.gradle file, which is the common parent to build descriptors that do stuff with the CAS web application. Making changes in this file will ensure it to be included by default in the generic CAS web application, regardless of how it is configured to run, which means you need to be extra careful about the sort of changes you make, what is kept and what is checked in here.

That said, the webapp.gradle is usually where I myself put the module references in and I try to be extra careful to not keep them in the same file when I check changes in for review, etc. So for reference and our task at hand, the webapp.gradle file would look like the following:

dependencies {
    implementation project(":support:cas-server-support-captcha")

Note the reference locates the module using its full path. The next time you run bc, the final CAS web application will have enabled reCAPTCHA functionality when it’s booting up inside Apache Tomcat.

The remaining tasks are super similar to the earlier post; we locate the ValidateCaptchaAction component and make the relevant change there. We then run bc to run CAS locally again to test the change and lather-rinse-repeat until the desired functionality is there. Once done, you may the commit the change to a relevant branch (of your fork, which is something you should have done earlier when you cloned the codebase) and push upstream (again, to your fork) in order to prepare a pull request and send in the change.

Debugging CAS

One of the very useful things you can include in your build is the ability to allow for remote debugging via -DenableRemoteDebugging=true. Both IntelliJ IDEA and eclipse allow you ways to connect to this port remotely and activate a debugger in order to step into the code and troubleshoot. This is hugely useful, especially in cases where you can make a change to a source file and rebuild the component live and hot, reloading the .class file and allowing the changes to kick in the very next time execution passes through without restarting Tomcat. Depending on how significant the change is, this should save you quite a bit of time.


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

[1] There are ways to get around this limitation, by specifically downloading the source code for the exact CAS version at hand. I am skipping over those since they only lead to complications, suffering and further evil in most cases.

Related Posts

CAS 6.0.0 RC1 Feature Release

...in which I present an overview of CAS 6.0.0 RC1 release.

Get Productive with Shell Aliases

A collection of useful shell aliases, gathered over the years to help increase one's productivity and developer happiness.

feat(conventional_commits): signal breaking changes in commit titles

In which I suggest Conventional Commits should be enhanced to reflect the breakingness of commits in their commit message titles.

uPortal annual report, June 2018 edition

Ecoysystem. Releases. Community. Fiscal responsibility.

One Can Only Hope in Buchistan

A true story inspired by real events. Seriously. Bryan Cranston has been approached for the role of "Some".

Apereo CAS - Extending Webflows

Learn and master extending CAS 5 Spring Webflow definitions.

Apereo CAS - Administrative Endpoints & Monitoring

Gain insight into your running Apereo CAS deployment in production. Learn how to monitor and manage the server by using HTTP endpoints and gather metrics to diagnose issues and improve performance.

Apereo CAS - Custom Authentication & Attribute Sources

Master writing custom authentication handlers/schemes in CAS and learn how to design custom data sources that can produce user claims and attributes.

Apereo CAS - User Interface Customizations

A short tutorial on Apereo CAS user interface customizations, including themes, localization and dynamic views for all those who enjoy front-end development and suffer from instant gratification.

CAS Multifactor Authentication with Google Authenticator

A short walkthrough to demonstrate how one might turn on multifactor authentication with CAS using Google Authenticator, leveraging a variety of triggers.