WAR Overlay Installation
CAS installation is a fundamentally source-oriented process, and we recommend a WAR overlay (1)
project to organize customizations such as component configuration and UI design.
The output of a WAR overlay build is a
cas.war file that can be deployed
to a servlet container like Apache Tomcat.
See this guide to learn more.
What is a WAR Overlay?
Overlays are a strategy to combat repetitive code and/or resources. Rather than downloading the CAS codebase and building from source,
overlays allow you to download a pre-built vanilla CAS web application server provided by the project itself and override/insert specific behavior into it. At build time, the build installation process will attempt to download the provided
binary artifact first. Then the tool will locate your configuration files and settings made available
inside the same project directory and will merge those into the downloaded artifact in order to produce
one wholesome archive (i.e.
cas.war) . Overridden artifacts may include
process to successfully execute, the location and names of the overridden artifacts
locally must EXACTLY match that of those provided by the project
inside the originally downloaded archive. Java code in the overlay project’s
folder and resources in
src/main/resources will end up in the
folder of cas.war and they will be loaded by the classloader instead of resources with the same names in jar files inside
It goes without saying that while up-front ramp-up time could be slightly complicated, there are significant advantages to this approach:
- There is no need to download/build from the source.
- Upgrades are tremendously easier in most cases by simply adjusting the build script to download the newer CAS release.
- Rather than hosting the entire software source code, as the deployer you ONLY keep your own local customizations which makes change tracking much easier.
- Tracking changes inside a source control repository is very lightweight, again simply because only relevant changes (and not the entire software) is managed.
Most if not all aspects of CAS can be controlled by adding, removing, or modifying files in the overlay; it’s also possible and indeed common to customize the behavior of CAS by adding third-party components that implement CAS APIs as Java source files or dependency references.
The process of working with an overlay can be summarized in the following steps:
- Start with and build the provided basic vanilla build/deployment.
- Identify the artifacts from the produced build that need changes. These artifacts are generally produced by the build in the
builddirectory for Gradle. Use the gradle
- Copy the identified artifacts from the identified above directories over to the
- Create the
src/main/resourcesdirectories, if they don’t already exist.
- Copied paths and file names MUST EXACTLY MATCH their build counterparts, or the change won’t take effect. See the table below to understand how to map folders and files from the build to
- Create the
- After changes, rebuild and repeat the process as many times as possible.
- Double check your changes inside the built binary artifact to make sure the overlay process is working.
Do NOT copy everything produced by the build. Attempt to keep changes and customizations to a minimum and only grab what you actually need. Make sure the deployment environment is kept clean and precise, or you incur the risk of terrible upgrade issues and painful headaches.
CAS WAR Overlays
CAS WAR overlay projects described below are provided for reference and study.
CAS Overlay Initializr
Apereo CAS Initializr is a relatively new addition to the Apereo CAS ecosystem that allows you as the deployer to generate CAS WAR Overlay projects on the fly with just what you need to start quickly.
To learn more about the initializr, please review this guide.
CAS Overlay Template
You can download or clone the repositories below to get started with a CAS overlay template.
The below repositories point you towards their
You should always make sure the branch you are on matches the version of CAS you wish to configure and deploy. The
branch typically points to the latest stable release of the CAS server. Check the build configuration and if inappropriate,
git branch -a to see available branches, and then
git checkout [branch-name] to switch if necessary.
|Project||Build Directory||Source Directory|
|CAS WAR Overlay||
cas/build/cas-resources files are unzipped
gradle explodeWar in the overlay.
To construct the overlay project, you need to copy directories and files that you need to customize in the build directory over to the source directory.
The WAR overlay also provides additional tasks to explode the binary artifact first before re-assembling it again. You may need to do that step manually yourself to learn what files/directories need to be copied over to the source directory.
Note: Do NOT ever make changes in the above-noted build directory. The changeset will be cleaned out and set back to defaults every time you do a build. Put overlaid components inside the source directory and/or other instructed locations to avoid surprises.
CAS Configuration Server Overlay
See this Maven WAR overlay for more details.
To learn more about the configuration server, please review this guide.
See this guide for more info.
CAS can be deployed to a number of servlet containers. See this guide for more info.
Custom and Third-Party Source
It is common to customize or extend the functionality of CAS by developing Java components that implement CAS APIs or
to include third-party source by dependency references. Including third-party source is trivial; simply include
the relevant dependency in the overlay
Overlaying or modifying CAS internal components and classes, unless ABSOLUTELY required, should be a last resort and is generally considered a misguided malpractice. Where possible, avoid making custom changes to carry the maintenance burden solely on your own. Avoid carrying . You will risk the stability and security of your deployment. If the enhancement case is attractive or modest, contribute back to the project. Stop writing code, or rite it where it belongs.
In order to include custom Java source, it should
be included under a
src/main/java directory in the overlay project source tree.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 ├── src │ ├── main │ │ ├── java │ │ │ └── edu │ │ │ └── sso │ │ │ └── middleware │ │ │ └── cas │ │ │ ├── audit │ │ │ │ ├── CompactSlf4jAuditTrailManager.java │ │ │ ├── authentication │ │ │ │ └── principal │ │ │ │ └── UsernamePasswordCredentialsToPrincipalResolver.java │ │ │ ├── services │ │ │ │ └── JsonServiceRegistryDao.java │ │ │ ├── util │ │ │ │ └── X509Helper.java │ │ │ └── web │ │ │ ├── HelpController.java │ │ │ ├── flow │ │ │ │ ├── AbstractForgottenCredentialAction.java │ │ │ └── util │ │ │ ├── ProtocolParameterAuthority.java
Each release of CAS provides a curated list of dependencies it supports. In practice, you do not need to provide a version for any of these dependencies in your build configuration as the CAS distribution is managing that for you. When you upgrade CAS itself, these dependencies will be upgraded as well in a consistent way.
The curated list of dependencies contains a refined list of third party libraries. The list is available as a standard Bills of Materials (BOM). Not everyone likes inheriting from the BOM. You may have your own corporate standard parent that you need to use, or you may just prefer to explicitly declare all your configuration.
To take advantage of the CAS BOM at
org.apereo.cas:cas-server-support-bom, via Gradle, please use this guide
and configure the Gradle build accordingly.
(1) WAR Overlays