This post tries to provide some background for change and offers a simple solution for deployments that use project Lombok directly. Our starting position is based on the following:

• CAS 8.0.x
• Java 25

Annotation Processors

Beginning with JDK 23, javac no longer automatically discovers and executes annotation processors from the classpath. Historically, annotation processors like Lombok were automatically detected and executed if they were present on the compile classpath. However, with modern JDKd annotation processors must be explicitly declared. This is a deliberate security hardening decision in javac.

For CAS overlays and extensions that rely on Lombok where custom source code is involved, this means the following constructs (and likely more) will silently stop generating code:

@Getter
@Setter
@RequiredArgsConstructor
@Builder

Fix

If your CAS 8 deployment runs on Java 25 and builds via Apache Maven, the solution is simple and explicit: declare annotation processors via maven-compiler-plugin:

<properties>
    <lombok.version>1.18.42</lombok.version>
</properties>

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.15.0</version>
    <configuration>
        <release>25</release>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Being explicit about annotation processors makes builds deterministic, prevents accidental processor execution, and ultimately aligns with modern JDK expectations.

Note: Apereo CAS builds that are using Gradle should already be doing the right thing. You should not have to change anything!

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

The fastest route to a 10X engineer is to give them 0.1X the distractions. - Eric Meyer

While that is generally sensible advice, when it comes to CAS there are times where you wish to interrupt the CAS authentication flow and the present the end-user with notifications and announcements. A common use case deals with presenting a message board during the authentication flow to select users and then optionally require the audience to complete a certain task before CAS is able to honor the authentication request and establish a session. Examples of such messages tasks may include: “The kitchen’s menu today features Khash. Click here to get directions.” or “The office of compliance and regulations has announced a new policy on using forks. Click to accept, or forever be doomed with spoons”.

CAS has the ability to pause and interrupt the authentication flow to reach out to external services and resources, querying for status and settings that would then dictate how CAS should manage and control the SSO session. Interrupt services are able to present notification messages to the user, provide options for redirects to external services, etc.

In this post, we are going to take a brief look at what it takes to interrupt the authentication flow. This tutorial specifically focuses on:

• CAS 7.3.x
• Java 21

Interrupt Source

First and foremost, there needs to be an engine of some sort that is able to produce notifications and interruptions. CAS supports a range of such engines that are backed by JSON & Groovy resources, REST endpoints or one you decide to create and inject into the runtime.

For the purposes of this tutorial, I will be using a Groovy script. This strategy reaches out to a Groovy resource whose job is to dynamically calculate whether the authentication flow should be interrupted given the provided username and certain number of other parameters.

cas.interrupt.groovy.location=file:/path/to/your/interrupt.groovy

You can choose any path and filename you prefer.

Remember to include the below module in your CAS build if you intend to implement any sort of behavior with Apache Groovy and scripting. This includes evaluating policies, release attributes, modifying or customizing components, etc. Without the listed above module, Apache Groovy functionality and libraries will not be pulled into your CAS project and CAS would most likely fail to deliver at runtime.

implementation "org.apereo.cas:cas-server-core-scripting"

Interrupt Rules

Once you have defined the above setting and assuming your overlay is prepped with relevant configuration module, CAS will attempt to understand the interruption rules that are defined in the Groovy file. My rules are defined as such:

import org.apereo.cas.interrupt.*

def run(final Object... args) {
    def (principal,attributes,service,registeredService,requestContext,logger) = args

    if (dontYouLoveItWhenYouAreInterrupted(principal, attributes)) {
      def block = false
      def ssoEnabled = true
      return new InterruptResponse("Message", [link1:"google.com", link2:"yahoo.com"], block, ssoEnabled)
    }
    return new InterruptResponse(false)
}

The above ruleset says: Evaluate the current principal and its attributes using dontYouLoveItWhenYouAreInterrupted(...) (something you, yes you, have to complete) and then present the Message to the user with a number of links. Do not block the user and allow the SSO session to be established.

Note that this is the default strategy that allows the interrupt query and script to execute after the primary authentication event and before the single sign-on event. This means an authenticated user has been identified by CAS and by extension is made available to the interrupt, and interrupt has the ability to decide whether a single sign-on session can be established for the user.

The Looks

Once that is all in place, casuser will see something similar to the following screen, after having authenticated successfully:

Custom Interrupt Sources

In scenarios where the power of Groovy is not good enough for you, you can always create your own interrupt source in Java. If you wish to design your own interrupt strategy to make inquiries, register the following bean:

@Bean
public InterruptInquiryExecutionPlanConfigurer myInterruptConfigurer() {
    return plan -> {
        plan.registerInterruptInquirer(new MyInterruptInquirer());
    };
}

…and your implementation may potentially look like this:

class MyInterruptInquirer extends BaseInterruptInquirer {
    @Override
    protected InterruptResponse inquireInternal(Authentication authentication,
                                                RegisteredService registeredService,
                                                Service service, 
                                                Credential credential,
                                                RequestContext requestContext) {
      // Stuff happens...
    }
}

Interruptions Per Application

There may be scenarios where you want to conditionally activate the interrupt flow for a specific or group of applications. One rather obvious though possibly cumbersome way of doing this would be to account for the condition and the application in your InterruptInquirer implementation or script the logic you need in Groovy. One easier way of doing this would be to activate the interrupt flow for an application only when the authenticated user carries a certain attributes that matches a value:

{
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "^https://my.application.org.*",
  "name" : "MyApplication",
  "id" : 1,
  "webflowInterruptPolicy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceWebflowInterruptPolicy",
    "attributeName": "memberOf",
    "attributeValue": "^st[a-z]ff$"
  }
}

The above policy will activate the interrupt flow when logging into https://my.application.org or any of its child pages when the user has the attribute memberOf with at least a value matching the defined pattern.

A slightly more advanced way of doing this would be to move the trigger and activation logic inside the application record itself and use a modest Groovy script to build the condition:

{
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "^https://my.application.org.*",
  "name" : "MyApplication",
  "id" : 1,
  "webflowInterruptPolicy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceWebflowInterruptPolicy",
    "enabled": true,
    "groovyScript":
      '''
      groovy {
        logger.info("Current attributes received are [{}]", attributes)
        return username == 'testuser' && attributes.containsKey('family_name')
      }
      '''
  }
}

The above application policy will activate the interrupt flow when logging into https://my.application.org or any of its child pages when the authenticated username is testuser and the user has the attribute family_name with any value.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

This post tries to present a simple approach to determine whether CAS can accept SAML2 AuthnRequests and whether metadata attached to service providers sending the requests can be parsed and recognized. Our starting position is as follows:

• CAS 7.3.x
• Java 21

Background

To assist with troubleshooting and testing, instead of acting like a full SAML Service Provider, we do something much lighter:

We can generate minimal SAML2 AuthnRequests and send them to CAS using HTTP-Redirect binding. Our chosen service provider is randomly chosen from a list of known SP entityIDs that are registered with CAS. Then, we of course observe CAS’s behavior with the following measurements:

• If the response to our request is a redirect to login: Great, the request is accepted.
• If the response to our request is a 4xx or 5xx error: Ouch, the request is denied.

Again, we are not interested in receiving a SAML2 response, assertions, browser behavior, etc. All we care about is, does CAS like this request?

This approach can be modestly useful because if CAS can’t resolve an SP’s metadata, you’ll see it immediately. CAS may load metadata but still reject an SP because of ACS mismatches, signature failures, registration issues, etc. It may also be helpful to do this as a smoke-test after upgrades; you can blast a few hundred requests at it and see what breaks.

Solution

Here is our plan:

• We generate just enough SAML to get CAS to engage:

<samlp:AuthnRequest
  ID="_abc123"
  Version="2.0"
  IssueInstant="2026-01-30T12:00:00Z"
  Destination="https://cas.example.org/idp/profile/SAML2/Redirect/SSO"
  ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  AssertionConsumerServiceURL="https://sp.example.org/saml/acs">
  <saml:Issuer>https://sp.example.org/shibboleth</saml:Issuer>
</samlp:AuthnRequest>

• We then use HTTP-Redirect encoding to deflate, base64-encode and then finally url-encode the result.
• For SP selection, we can use a simple entities.txt file:

https://sp1.example.org/shibboleth
https://sp2.example.org/shibboleth
https://sp3.example.org/shibboleth

Each request randomly picks one entityID so you can try to get a healthy mix.

Here is how it works in practice:

#!/usr/bin/env bash
set -euo pipefail

IDP_SSO_URL="${IDP_SSO_URL:-https://cas.example.edu/cas/idp/profile/SAML2/Redirect/SSO}"
ENTITIES_FILE="${ENTITIES_FILE:-./entities.txt}"
COUNT="${COUNT:-10}"
MIN_DELAY="${MIN_DELAY:-1}"
MAX_DELAY="${MAX_DELAY:-2}"

SP_ACS_URL="${SP_ACS_URL:-}"
PROTOCOL_BINDING="${PROTOCOL_BINDING:-urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST}"

FORCE_AUTHN="${FORCE_AUTHN:-false}" 
IS_PASSIVE="${IS_PASSIVE:-false}"   

LOG_FILE="${LOG_FILE:-./saml_idp_ping.log}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    -u) IDP_SSO_URL="$2"; shift 2 ;;
    -f) ENTITIES_FILE="$2"; shift 2 ;;
    -n) COUNT="$2"; shift 2 ;;
    --min) MIN_DELAY="$2"; shift 2 ;;
    --max) MAX_DELAY="$2"; shift 2 ;;
  esac
done

if [[ ! -f "$ENTITIES_FILE" ]]; then
  echo "Entities file not found: $ENTITIES_FILE" >&2
  exit 2
fi

if ! command -v python3 >/dev/null 2>&1; then
  echo "python3 is required (used for DEFLATE+Base64+URL-encode)." >&2
  exit 2
fi


pick_random_entity() {
  awk '
    NF && $1 !~ /^#/ {
      lines[NR]=$0
    }
    END {
      if (NR > 0) {
        srand()
        print lines[int(rand()*NR)+1]
      }
    }
  ' "$ENTITIES_FILE"
}

rand_id() {
  if command -v openssl >/dev/null 2>&1; then
    echo "_$(openssl rand -hex 16)"
  else
    echo "_$(date +%s%N)_$RANDOM"
  fi
}

iso_instant() {
  date -u +"%Y-%m-%dT%H:%M:%SZ"
}

deflate_b64_urlencode() {
  python3 -c 'import sys,zlib,base64,urllib.parse
data = sys.stdin.buffer.read()
compressed = zlib.compress(data)[2:-4]
b64 = base64.b64encode(compressed).decode("ascii")
print(urllib.parse.quote(b64, safe="~()*!.\x27"))'
}

urlencode() {
  python3 -c 'import sys,urllib.parse
print(urllib.parse.quote(sys.stdin.read().strip(), safe="~()*!.\x27"))'
}

sleep_random_1to2() {
  awk -v min="$MIN_DELAY" -v max="$MAX_DELAY" '
    BEGIN {
      srand()
      print min + rand() * (max - min)
    }
  ' | xargs sleep
}

build_authn_request_xml() {
  local entity_id="$1"
  local req_id="$2"
  local issue_instant="$3"

  cat <<XML
<samlp:AuthnRequest
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="${req_id}"
  Version="2.0"
  IssueInstant="${issue_instant}"
  Destination="${IDP_SSO_URL}"
  ProtocolBinding="${PROTOCOL_BINDING}"
  ForceAuthn="${FORCE_AUTHN}"
  IsPassive="${IS_PASSIVE}">
  <saml:Issuer>${entity_id}</saml:Issuer>
  <samlp:NameIDPolicy
    Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
    AllowCreate="true"/>
</samlp:AuthnRequest>
XML
}

send_one() {
  local i="$1"
  local entity_id="$2"
  local req_id="$3"
  local issue_instant="$4"
  local relay_state="rs-${i}-$(date +%s)"

  local xml
  xml="$(build_authn_request_xml "$entity_id" "$req_id" "$issue_instant")"

  local saml_request

  saml_request="$(printf "%s" "$xml" | deflate_b64_urlencode)"

  local relay_enc
  relay_enc="$(printf "%s" "$relay_state" | urlencode)"

  local url="${IDP_SSO_URL}?SAMLRequest=${saml_request}&RelayState=${relay_enc}"

  local tmp_body
  tmp_body="$(mktemp)"
  local hdrs
  hdrs="$(mktemp)"

  local http_code
  http_code="$(
    curl -sS -D "$hdrs" -o "$tmp_body" \
      --connect-timeout 10 --max-time 20 \
      "$url" \
      -w "%{http_code}"
  )"

  local location
  location="$(
    tr -d '\r' < "$hdrs" \
    | awk 'BEGIN{IGNORECASE=1} /^location:/ {sub(/^location:[[:space:]]*/,""); loc=$0} END{print loc}'
  )"

  local ts
  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"


  local verdict="UNKNOWN"
  if [[ "$http_code" =~ ^30[12]$ ]]; then
    verdict="REDIRECT"
  elif [[ "$http_code" =~ ^2 ]]; then
    verdict="OK_2XX"
  elif [[ "$http_code" =~ ^4 ]]; then
    verdict="CLIENT_4XX"
  elif [[ "$http_code" =~ ^5 ]]; then
    verdict="SERVER_5XX"
  fi

  {
    echo "[$ts] #$i entityID=\"$entity_id\" reqID=\"$req_id\" http=$http_code verdict=$verdict location=\"${location}\""
  } | tee -a "$LOG_FILE"

  # If it looks like a failure, include a small snippet of the body in the log
  # if [[ "$http_code" =~ ^4|^5 ]]; then
  #   local snippet
  #   snippet="$(tr '\n' ' ' < "$tmp_body" | sed 's/[[:space:]]\+/ /g' | cut -c1-500)"
  #   echo "  body_snippet: ${snippet}" | tee -a "$LOG_FILE"
  # fi

  rm -f "$tmp_body" "$hdrs"
}


echo "Logging to: $LOG_FILE"
echo "IdP SSO URL: $IDP_SSO_URL"
echo "Entities:    $ENTITIES_FILE"
echo "Count:       $COUNT"
echo "Delay:       ${MIN_DELAY}-${MAX_DELAY}s"
echo "ACS URL:     $SP_ACS_URL"
echo "Binding:     $PROTOCOL_BINDING"
echo "ForceAuthn:  $FORCE_AUTHN"
echo "IsPassive:   $IS_PASSIVE"

rm -f "$LOG_FILE" || true
echo "===================================="
echo "===================================="

echo "----" | --- tee -a "$LOG_FILE" >/dev/null 2>&1 || true
echo "----" >> "$LOG_FILE"

for ((i=1; i<=COUNT; i++)); do
  entity_id="$(pick_random_entity)"
  if [[ -z "$entity_id" ]]; then
    echo "No entityIDs found in $ENTITIES_FILE (empty or only comments)." >&2
    exit 2
  fi

  req_id="$(rand_id)"
  issue_instant="$(iso_instant)"
  send_one "$i" "$entity_id" "$req_id" "$issue_instant"
  sleep_random_1to2
done

Once you are ready:

• Make sure you can run the script: chmod +x ./script.sh.
• Modify the ./entities.txt file with the list of entity IDs you want to test; one per line, as many as you like.
• Modify the script to adjust the variables at the top. Specifically, IDP_SSO_URL and COUNT (number of attempts to run). You can also adjust the delay between each request.
• Run the script: ./script.sh.

You will see the verdict and the resulting HTTP code for each attempt. Watch out for verdicts that result in a 4xx/5xx error, and let the script run for a while for a large number of attempts.

To better simulate a load test, you can opt for shorter delays:

MIN_DELAY="${MIN_DELAY:-.1}"
MAX_DELAY="${MAX_DELAY:-.1}"

Or, replace the contents of sleep_random_1to2() with a benign statement like: echo "...".

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

Our starting position is as follows:

• CAS 7.3.x
• Java 21

The Goal

Ideally, when CAS deployments are built into a .war file, we would want to ship only the Java modules we actually need. We can package the modules and bundle them with the CAS application and have it look, feel and run as a native-looking executable. This way, there is no unpredictable runtime behavior, no external Java dependency and a smaller/simpler deployment with a self-contained CAS deployment.

Our solution here does not require a Java dependency on the target machine that runs CAS. You simply drop the final executable in the target environment and run it. It also has a smaller attack surface, since we are not shipping with a full JDK but with a trimmed, smaller set of Java modules with fewer classes and native libs.

In other words, you have Docker, but without Docker. 😎

The How

Our approach is something along the following lines:

• Use jdeps to determine which JDK modules are actually used by CAS.
• Use jlink to build a custom Java runtime containing only those modules.
• Use jpackage to bundle the runtime and CAS into a native launcher (for example, a .app on macOS).

The end result is a single CAS bundle you can copy to another machine and run — even if Java is not installed there.

Here is a script that does that:

#!/usr/bin/env bash
set -euo pipefail

if [[ "${1:-}" == "" ]]; then
  echo "ERROR: Missing WAR path."
  echo "Usage: $0 /path/to/app.war \"MyApp\""
  exit 1
fi

APP_WAR="$(cd "$(dirname "$1")" && pwd)/$(basename "$1")"
if [[ ! -f "$APP_WAR" ]]; then
  echo "ERROR: WAR not found: $APP_WAR"
  exit 1
fi

APP_NAME="${2:-MyApp}"

WORK_DIR="${WORK_DIR:-./build/jlink-work}"
JPACKAGE_TYPE="${JPACKAGE_TYPE:-app-image}"

EXTRA_MODULES="${EXTRA_MODULES:-}"
JAVA_OPTS="${JAVA_OPTS:-}"

need_cmd() {
  command -v "$1" >/dev/null 2>&1 || {
    echo "ERROR: Required command not found on PATH: $1"
    exit 1
  }
}

join_by_comma() {
  local a="${1:-}"
  local b="${2:-}"
  if [[ -n "$a" && -n "$b" ]]; then
    echo "${a},${b}"
  elif [[ -n "$a" ]]; then
    echo "$a"
  else
    echo "$b"
  fi
}

emit_jpackage_java_options() {
  local opts="$1"
  if [[ -z "$opts" ]]; then
    return 0
  fi
  for o in $opts; do
    printf -- " --java-options %q" "$o"
  done
}

need_cmd jar
need_cmd jdeps
need_cmd jlink
need_cmd jpackage

JAVA_VERSION="$(java -version 2>&1 | head -n 1 || true)"
echo "==> Using Java: $JAVA_VERSION"
echo "==> WAR: $APP_WAR"
echo "==> App Name: $APP_NAME"
echo "==> Work Dir: $WORK_DIR"
echo "==> jpackage type: $JPACKAGE_TYPE"
echo "==> EXTRA_MODULES: $EXTRA_MODULES"
echo "==> JAVA_OPTS: $JAVA_OPTS"
echo

rm -rf "$WORK_DIR"
mkdir -p "$WORK_DIR"
cp "$APP_WAR" "$WORK_DIR/app.war"

echo "==> Step 1/3: Analyze with jdeps"
mkdir -p "$WORK_DIR/war"
(
  cd "$WORK_DIR/war"
  jar xf ../app.war
)

JDEPS_MODULES="$(
  jdeps \
    --multi-release 25 \
    --ignore-missing-deps \
    --recursive \
    --print-module-deps \
    --class-path "$WORK_DIR/war/WEB-INF/lib/*" \
    "$WORK_DIR/war/WEB-INF/classes" \
  | tr -d '[:space:]'
)"

if [[ -z "$JDEPS_MODULES" ]]; then
  echo "ERROR: jdeps returned an empty module set."
  exit 1
fi

MODULES="$(join_by_comma "$JDEPS_MODULES" "$EXTRA_MODULES")"
if [[ "${FORCE_JAVA_DESKTOP:-false}" != "true" ]]; then
  MODULES="$(echo "$MODULES" | sed 's/\(^\|,\)java\.desktop\(,\|$\)/\1\2/g' \
    | sed 's/,,*/,/g; s/^,//; s/,$//')"
fi
if [[ "${FORCE_JFR:-false}" != "true" ]]; then
  MODULES="$(echo "$MODULES" | sed -E 's/(^|,)(jdk\.jfr|jdk\.management\.jfr)(,|$)/\1\3/g' \
    | sed 's/,,*/,/g; s/^,//; s/,$//')"
fi

echo "==> jdeps modules:"
echo "    $JDEPS_MODULES"
echo "==> final module set (with extras):"
echo "    $MODULES"
echo

echo "==> Step 2/3: Build minimal runtime with jlink"
jlink \
  --add-modules "$MODULES" \
  --strip-debug \
  --no-header-files \
  --no-man-pages \
  --compress=zip-9 \
  --output "$WORK_DIR/runtime"

echo "==> Runtime image created at: $WORK_DIR/runtime"
echo


echo "==> Step 3/3: Package with jpackage"
mkdir -p "$WORK_DIR/dist"
cp "$WORK_DIR/app.war" "$WORK_DIR/dist/"

JPACKAGE_CMD="jpackage \
  --type $JPACKAGE_TYPE \
  --name $(printf %q "$APP_NAME") \
  --input $(printf %q "$WORK_DIR/dist") \
  --main-jar app.war \
  --runtime-image $(printf %q "$WORK_DIR/runtime") \
  --dest $(printf %q "$WORK_DIR/out")"


JPACKAGE_CMD+=$(emit_jpackage_java_options "$JAVA_OPTS")

echo "==> Running:"
echo "    $JPACKAGE_CMD"
echo

eval "$JPACKAGE_CMD"

echo
echo "==> Done."
echo "==> Output located at: $WORK_DIR/out"
if [[ "$JPACKAGE_TYPE" == "app-image" ]]; then
  echo "==> App image folder: $WORK_DIR/out/$APP_NAME"
  echo "    Try running the launcher inside that folder."
else
  echo "==> Installer/package created under: $WORK_DIR/out"
fi

To run this, you first need to build and package your CAS server into a .war file:

./gradlew clean build

Then:

./the-above-script.sh ./build/libs/cas.war cas

You should see the following output:

==> Using Java: openjdk version "21.0.8" 2025-07-15 LTS
==> WAR: /work/cas-overlay-template/build/libs/cas.war
==> App Name: cas
==> Work Dir: ./build/jlink-work
==> jpackage type: app-image
==> EXTRA_MODULES: 
==> JAVA_OPTS: -Xms512m -Xmx6048m -Xss64m -XX:ReservedCodeCacheSize=512m -XX:+UseG1GC

==> Step 1/3: Analyze with jdeps
==> jdeps modules:
    java.base,java.compiler,java.desktop,java.instrument,...
==> final module set (with extras):
    java.base,java.compiler,java.desktop,java.instrument,...

==> Step 2/3: Build minimal runtime with jlink
==> Runtime image created at: ./build/jlink-work/runtime

==> Step 3/3: Package with jpackage
==> Running:
    jpackage --type app-image --name cas --input ./build/jlink-work/dist   \
      --main-jar cas.war   --runtime-image ./build/jlink-work/runtime  \
      --dest ./build/jlink-work/out --java-options -Xms512m --java-options -Xmx6048m \
      --java-options -Xss64m --java-options -XX:ReservedCodeCacheSize=512m \
      --java-options -XX:+UseG1GC

==> Done.
==> Output located at: ./build/jlink-work/out
==> App image folder: ./build/jlink-work/out/cas
    Try running the launcher inside that folder.

Since I am running this on MacOS, the end result is:

ls build/jlink-work/out/cas.app

Permissions Size User   Group Date Modified Name
drwxr-xr-x     - misagh staff 31 Jan 09:59  Contents/

Which means I can also run the CAS server on its own now:

./build/jlink-work/out/cas.app/Contents/MacOS/cas

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

In this post, we will take a quick look at the theme options available to CAS that allow one to remember the username. Our starting position must be:

• CAS 8.0.x
• Java 25

Theme Configuration

More recent versions of CAS have the ability to capture and remember the submitted username. The captured username is tracked and stored by the browser’s localStorage facility and can be cleared on demand. While this capability of themes is off by default, it’s relatively simple to allow the server to enable this behavior.

To do so, you will need the following setting in a src/main/resources/cas-theme-custom.properties file:

cas.login-form.remember-username.enabled=true

The cas-theme-custom.properties file, intentionally left blank by default, allows you to override specific settings in the default CAS theme. When enabled, please note that this feature is only operational if the public workstation functionality if turned off, which is the default:

cas.public-workstation.enabled=false

Once public workstation functionality enabled, usernames will no longer be captured and stored.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

In this post, we will take a quick look at what Compact Object Headers are and how a CAS deployment can run with this feature enabled. Our starting position must be:

• CAS 8.0.x
• Java 25

Compact Object Headers

Compact Object Headers were an experimental feature in Java 24, and you had to unlock experimental options to use them (e.g., -XX:+UnlockExperimentalVMOptions). This is no longer necessary with Java 25 and activation of this feature requires the flag -XX:+UseCompactObjectHeaders, as in:

java -XX:+UseCompactObjectHeaders $OTHER_FLAGS_HERE -jar build/libs/cas.war 

The premise here is that using Compact Object Headers will reduce the per-object memory overhead in the JVM and objects get smaller. This sort of compression improves memory efficiency and often performance because, say, a CAS deployment at runtime will require less total heap memory which leads to lower GC pressure and better cache management and object pointer chansing by the CPU.

It would be an interesting exercise to benchmark CAS deployments under heavy load with Compact Object Headers enabled/disabled and compare results.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

In this blog post, we will briefly review the setup and configuration required to enable and run the Palantir admin dashboard. Our starting position is based on:

• CAS 8.0.x
• Java 25

Setup

At its core, Palantir builds on top of the available and exposed actuator endpoints that are provided by the underlying frameworks such as Spring Boot as well as those that CAS itself presents. It does have the smarts to some degree to figure out which actuator endpoints are available and can then rearrange itself to show relevant content and operations.

The most basic setup requires that you enable the following CAS modules:

implementation "org.apereo.cas:cas-server-support-palantir"
implementation "org.apereo.cas:cas-server-support-reports"

Once in place and to keep matters simple and demo-worthy, we may enable and expose all actuator endpoints that are available to our current CAS build for public access:

cas.monitor.endpoints.endpoint.defaults.access=ANONYMOUS
management.endpoints.web.exposure.include=*
management.endpoints.access.default=UNRESTRICTED

Furthermore, we may define a single admin account that is able to access the Palantir dashboard:

spring.security.user.name=casadmin
spring.security.user.password=...YOUR_PASSWORD_HERE...

For a slightly more advanced option, you may define the admin accounts in an external JSON file:

cas.monitor.endpoints.endpoint.defaults.access=ROLE
cas.monitor.endpoints.endpoint.defaults.required-roles=ADMIN

cas.monitor.endpoints.json.location=file:/path/to/MyUsers.json

…where the file would be:

[
  {
    "username": "casadmin",
    "password": "{sha512}b6c65a...",
    "authorities": [
      "ROLE_ADMIN"
    ]
  },
  {
    "username": "casnone",
    "password": "{noop}pa$$w0rd"
  }
]

Capabilities

Remember that Palantir builds on top of the available and exposed actuator endpoints that are brought into the build by various CAS modules. Palantir functionality and features will become conditionally available depending on what is included in the build. Of course, not all functionality is exposed via dedicated actuator endpoints comprehensively, and not every feature behind an existing actuator endpoint is yet supported by Palantir. Having said that, the following capabilities are offered by the Palantir admin dashboard.

Application Dashboard

Palantir offers an application dashboard that lists all current applications registered with CAS:

You may choose to edit the application registration record directly:

You may also choose a wizard-based approach to register a new application with CAS step by step:

You can verify whether an application has access to CAS:

Or get a quick view of SAML2 service providers and their metadata source:

System Status

You may observe and monitor the server status, HTTP requests, etc.

Ticket Registry

You can interact with the effective ticket registry:

You may also query for effective SSO sessions and administratively log users out:

Logging

You can control application log levels:

Or monitor and watch log activity live:

CAS Configuration

You can examine CAS configuration properties and sources:

Or look up users and their attributes from configured sources:

Or look up configured authentication sources and providers:

Or interact with protocol-specific functionality to run simulations, etc.

Multifactor Authentication

You can look up registered multifactor devices for users for providers that support device registration and management, such as Duo Security, Google Authenticator, etc.

Limitations & Caveats

Palatir does offer a lot, and is being consistently improved and worked on to present more capabilities or enhance what is already available. That said, some things in Palantir are not available as of this writing, some of which are noted here:

• The wizard-based application editor does not support every single configuration setting that can be assigned to an application record. YMMV.
• The wizard-based application editor does not support advanced concepts such as chaining policies, etc.

• Lots of functionality is presented in read-only mode only, and writes/updates are not possible. A concrete example would be updating a CAS configuration property.
• Palantir user interfaces may be entirely dysfunctional if the CAS user interface is modified and themed heavily or if certain core CSS and JavaScript libraries are removed during customizations. The Palantir admin dashboard and the rest of the CAS user interface inherit the same common layout and libraries, and changing one may have adverse effects on the other.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

In this post, we will briefly review options that allow a CAS deployment to safely extract the client IP address from HTTP requests. Our starting position is as follows:

• CAS 7.3.x
• Java 21

The Problem

A CAS deployment (or any web application for that matter) must never trust the X-Forwarded-For header (or any other header) unless it is set/overwritten by a trusted proxy, and we must then make sure CAS is configured to only use that trusted information. By default, CAS is configured to extract and read the X-Forwarded-For header directly from the request, assuming that that header is validated and set by a trusted proxy. Failure to do so will have CAS blindly trust the X-Forwarded-For header as provided by the client, allowing certain security restrictions that are IP-based to be bypassed.

Reverse Proxies & Load Balancers

One mitigation strategy is to ensure that only a trusted component (reverse proxy/load balancer) can set X-Forwarded-For, and that CAS only uses that trusted info. To do this, one must terminate untrusted traffic at a reverse proxy (nginx, HAProxy, Apache httpd, etc.) and configure the proxy to strip any incoming X-Forwarded-For header from the client. The reverse proxy would then set a new X-Forwarded-For header (or Forwarded) based on the real remote_addr it sees.

In other words, you must not deploy CAS directly on the internet with X-Forwarded-For as the default mechanism, unless you are stripping and re-setting the header at a trusted boundary. Otherwise, the deployment is vulnerable to a wide range of security issues and problems.

An example setup with nginx might be:

location /cas {
  proxy_pass http://cas_upstream;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-Port $server_port;

  # Optional: Forwarded header (RFC 7239)
  proxy_set_header Forwarded "for=$remote_addr;proto=$scheme;host=$host";
}

This prevents spoofing because nginx never forwards what the client sent; it overwrites with $remote_addr (what nginx actually saw at the TCP layer). If a malicious client sends X-Forwarded-For: 8.8.8.8, it gets ignored and replaced.

A quick test with curl might be:

curl -k -H 'X-Forwarded-For: 8.8.8.8' https://sso.example.org/cas/login -v

If the reverse proxy is configured and doing its job correctly, CAS should see your actual client IP, not 8.8.8.8.

Apache Tomcat

If your reverse proxy is unable to recreate headers, you may be able to take advantage of similar functionality provided by your servlet container. For example, Apache Tomcat has a RemoteIpValve whose purpose is to replace the apparent remote IP address, hostname, scheme (HTTP/HTTPS), and server port of an incoming request. To recap, the most common headers used are:

• X-Forwarded-For: Contains a list of IP addresses that traversed the request, with the original client’s IP being the first one.
• X-Forwarded-Proto: Indicates the protocol (e.g., http or https) the client used to connect to the proxy.
• X-Forwarded-Host: Indicates the original hostname requested by the client.

The RemoteIpValve reads these headers and uses the information to internally modify the request that CAS sees. By default, CAS (in collaboration with Spring Boot) presents an opinionated set of configurations that configure this component, and your task is mainly to define the internal and trusted proxies that allow the RemoteIpValve to operate on the request:

server.tomcat.remoteip.internal-proxies=172\\..+
server.tomcat.remoteip.trusted-proxies=172\\..+

The above configuration says: only if the immediate peer is 172.x.x.x (i.e., nginx in a docker network) will Apache Tomcat honor forwarding headers.

What happens in practice is:

• When a new request is submitted, RemoteIpValve decides whether to rewrite the request’s “remote address” based on whether the TCP peer (the original value found in request.getRemoteAddr()) matches your configured internal/trusted proxies.
• Let’s imagine that our TCP peer is 192.168.65.1, which is commonly the host-side gateway/NAT address used by Docker Desktop when your host talks to containers. Since 192.168.65.1 doesn’t match the trusted/internal proxy patterns, Apache Tomcat correctly says: “this request did not come from a trusted proxy, so I will ignore forwarded headers.”

It is important to note that, in this scenario, Apache Tomcat does not remove headers from the request. So a spoofed X-Forwarded-For header will still be present and CAS may read it directly if configured. We can disable this behavior and remove the risk via:

cas.audit.engine.alternate-client-addr-header-name=

Setting this property to blank will force CAS to not read the header directly, and instead uses request.getRemoteAddr() provided by the proxy.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

In this post, we will briefly review an option that would allow one to hotswap code at runtime. Our starting position is as follows:

• CAS 7.3.x
• Java 21

Approach

While there are commercial tools out there, such as JRebel, free and/or open-source alternative solutions for dynamically loading or hot reloading Java code at runtime vary in capability or maturity from basic method-level changes to full structural class redefinitions, and often require specific JVM or IDE configurations. This post will focus on using the JetBrains Runtime (JBR).

JetBrains Runtime (JBR) for Java

JetBrains Runtime (JBR) is a customized OpenJDK distribution optimized for development, particularly with JetBrains IDEs like IntelliJ IDEA. It includes enhancements like improved font rendering, better desktop integration, optional Java Chromium Embedded Framework (JCEF) for browser embedding, and crucially, enhanced class redefinition (via DCEVM-like functionality) for dynamic code reloading during debugging—useful as an alternative to tools like DCEVM for hot-swapping changes without full restarts. This is enabled by the JVM flag -XX:+AllowEnhancedClassRedefinition.

What this practically means that while you’re in debug mode, JBR’s enhanced redefinition allows reloading method bodies, adding/removing fields/methods, and more beyond standard HotSwap. Moreover, JBR passes OpenJDK TCK tests, ensuring compatibility.

Note on Java 25

As of this writing, JBR supports Java 25, though adoption may lag slightly behind standard OpenJDK. IntelliJ IDEA 2025.2 and later fully support Java 25 development with JBR, including preview features like compact source files and module imports. If you’re not using a JetBrains IDE, worry not! JBR can still serve as your project’s JDK/JRE for building, running, and debugging apps.

Configuration

You do not need to manually download and configure the JBR. This is something that can be achieved with Gradle’s support for Java Toolchains:

java {
  toolchain {
    languageVersion = JavaLanguageVersion.of(21)
    vendor = JvmVendorSpec.JETBRAINS
  }
}

For this to work, you must make sure your settings.gradle file contains the foojay plugin definition:

plugins {
  id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

Now, Gradle will auto-download JBR 25 if not present already once you build the application with ./gradlew build. The Foojay Toolchains plugin (via the org.gradle.toolchains.foojay-resolver-convention plugin) automatically downloads and provisions JBR (or other JDKs you need them) if it’s not already available on the system. It uses Gradle’s built-in auto-detection but falls back to downloading from the Foojay Disco API (which supports JetBrains as a vendor).

To verify, you can also run ./gradlew javaToolchains, which lists all detected/provisioned toolchains with paths.

Spring Boot

Once you run CAS with ./gradlew bootRun, Gradle will start CAS using JetBrains Runtime 25 and you will get much better hot-swapping capability for things like adding/removing/changing method bodies or methods in general, changing method signatures in many cases, some interface and/or interface hierarchy changes, etc. This is already excellent!

One important detail is still missing for full hot-swapping (adding/removing methods, fields, changing hierarchies, etc). For this to fully function, you will need to modify the bootRun task as well to include the special flag XX:+AllowEnhancedClassRedefinition. This is because JBR ships with the enhanced redefinition capability built-in, but it is disabled by default for stability reasons. You must explicitly turn it on.

bootRun {
    // Other stuff happens here...

    def list = []

    // Other stuff happens here...

    list.add("-XX:+AllowEnhancedClassRedefinition")

    // Other stuff happens here...

    jvmArgs = list
    
    // Other stuff happens here...
    ...
}

After adding this line and applying the change, run:

./gradlew bootRun

HotSwapAgent

For maximum benefit, you can also combine JBR and the flag above with HotSwapAgent. This agent adds Spring bean reloads on config changes, Hibernate entity reloads, resource file reloads and a better overall framework integration.

You need to add the agent JAR (download from here) to the same construct you had above:

bootRun {
    // Other stuff happens here...

    list.add("-XX:+AllowEnhancedClassRedefinition")
    list.add("-javaagent:/path/to/hotswap-agent.jar=autoHotswap=true")

    // Other stuff happens here...
}

Now you’re really cooking with gas!

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed

This tutorial specifically requires and focuses on:

• CAS 7.3.x
• Java 21

Overlay…What?

Overlays are a strategy to combat repetitive code and/or resources. Rather than downloading the CAS codebase and building it from source, overlays allow you to download a pre-built vanilla CAS web application server provided by the project itself, override/insert specific behavior into it and then merge it all back together to produce the final (web application) artifact. You can find a lot more about how overlays work here.

Please note that a CAS WAR Overlay can also be generated on demand using the CAS Initializr.

The concept of the WAR Overlay is NOT a CAS invention. It’s specifically an Apache Maven feature and of course, there are techniques and plugins available to apply the same concept to Gradle-based builds as well. For this tutorial, the Gradle overlay we will be working with is available here. Be sure to check out the appropriate branch, that is 7.3.

The quickest way to generate a CAS WAR overlay starter template is via the following:

curl -k https://getcas.apereo.org/starter.tgz  \
  -d type=cas-overlay -d baseDir=overlay | tar -xzvf -

…if you prefer, you could always download and clone this repository.

Once you have forked and cloned the repository locally, or when you have generated the WAR overlay yourself using CAS Initializr, you’re ready to begin.

Overlay’s Anatomy

Similar to Grey’s, a Gradle WAR overlay is composed of several facets the most important of which are the build.gradle and gradle.properties file. These are build-descriptor files whose job is to teach Gradle how to obtain, build, configure (and in certain cases deploy) CAS artifacts.

The CAS Gradle Overlay is composed of several sections. The ones you need to worry about are the following.

Gradle Properties

In gradle.properties file, project settings, and versions are specified:

cas.version=7.3.0

The gradle.properties file describes what versions of CAS, Spring Boot, and Java are required for the deployment. You are in practice mostly concerned with the cas.version setting and as new (maintenance) releases come out, it would be sufficient to simply update that version and re-run the build.

This might be a good time to review the CAS project’s Release Policy as well as Maintenance Policy.

To Upgrade

You should do your best to stay current with CAS releases, particularly those that are issued as security or patch releases. Security releases are a critical minimal change on a release to address a serious confirmed security issue, and typically take on the format of X.Y.Z.1, X.Y.Z.2, etc. A patch release is a conservative incremental improvement that includes bug fixes and is absolutely backward compatible with previous patch releases and takes on the format of X.Y.1, X.Y.2, etc.

Upgrading to a security or patch release is STRONGLY recommended, and should be a drop-in replacement. To upgrade to such releases, all you should have to do is to adjust the cas.version setting in your gradle.proprties file. For example, going from CAS 7.3.0 to 7.3.1 should be as easy as:

# cas.version=7.3.0
cas.version=7.3.1

The best way to stay current with CAS releases and receive release notifications and announcements is via subscribing to the GitHub repository and watch for releases:

Dependencies

The next piece describes the dependencies of the overlay build. These are the set of components almost always provided by the CAS project that will be packaged up and put into the final web application artifact.

Here is an example:

dependencies {
  /**
    * CAS dependencies and modules may be listed here.
    *
    * There is no need to specify the version number for each dependency
    * since versions are all resolved and controlled by the dependency management
    * plugin via the CAS bom.
    **/
}

Note that when you include dependencies in the CAS build, you do not need to specify the CAS version itself. 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 Bill of Materials (BOM).

depndencies {
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    // Include the CAS reports module without its version
    implementation "org.apereo.cas:cas-server-support-reports"
}

Including a CAS module/dependency in the build.gradle simply advertises to CAS your intention of turning on a new feature or a variation of current behavior. Do NOT include something in your build just because it looks and sounds cool. Remember that the point of an overlay is to only keep track of things you need and care about, and no more.

The Build

Now that you have a basic understanding of the build descriptor, it’s time to run the build. A Gradle build is often executed by passing specific goals/commands to Gradle itself, aka gradlew. So for instance in the terminal and once inside the project directory you could execute things like:

cd cas-overlay-template
./gradlew clean

The WAR Overlay project provides you with an embedded Gradle wrapper whose job is to first determine whether you have Gradle installed. If not, it will download and configure one for you based on the project’s needs. The gradlew tasks command describes the set of available operations you may carry out with the build script.

As an example, here’s what I see if I were to run the build command:

./gradlew clean copyCasConfiguration build

...
Starting a Gradle Daemon (subsequent builds will be faster)
Configuration on demand is an incubating feature.

BUILD SUCCESSFUL in 14s
2 actionable tasks: 2 executed
...

You can see that the build attempts to download, clean, compile and package all artifacts, and finally, it produces a build/libs/cas.war which you can then use for actual deployments.

Configuration

I am going to skip over the configuration of /etc/cas/config and all that it deals with. If you need the reference, you may always use this guide to study various aspects of CAS configuration.

Suffice it to say that, quite simply, CAS deployment expects the main configuration file to be found under /etc/cas/config/cas.properties. This is a key-value store that can dictate and alter the behavior of the running CAS software.

As an example, you might encounter something like:

cas.server.name=https://cas.example.org:8443
cas.server.prefix=${cas.server.name}/cas
logging.config=file:/etc/cas/config/log4j2.xml

…which at a minimum, identifies the CAS server’s URL and prefix and instructs the running server to locate the logging configuration at file:/etc/cas/config/log4j2.xml. The overlay by default ships with a log4j2.xml that you can use to customize logging locations, levels, etc. Note that the presence of all that is contained inside /etc/cas/config/ is optional. CAS will continue to fall back onto defaults if the directory and the files within are not found.

Keep Track

It is VERY IMPORTANT that you contain and commit the entire overlay directory (save the obvious exclusions such as the build directory) into some sort of source control system, such as git. Treat your deployment just like any other project with tags, releases, and functional baselines.

Logging

CAS server logs are THE BEST RESOURCE for determining the root cause of a problem, provided you have configured the appropriate log levels. Specifically, you want to make sure DEBUG or TRACE levels are turned on for the relevant packages and components in your logging configuration. Know where the logging configuration is, become familiar with its syntax when changes are due and know where the output data is saved.

Configuration

The CAS server web application by default ships with a log4j2.xml file that provides sensible logging configuration and levels for basic use cases. This option typically is activated when no external logging configuration is available and provided by the CAS build or its configuration. In reality, the CAS build provides dedicated settings by default to control the loggig configuration via the following setting:

logging.config=file:/etc/cas/config/log4j2.xml

The logging configuration is then expected to be found and loaded from /etc/cas/config/log4j2.xml. If you deactivate or remove this setting, the default logging described earlier will begin to activate.

Log Output

Log messages are routed to console, and a cas.log file at /tmp/logs. Here are a few points about the default logging facility:

• You can change the base directory by passing along a system property to the runtime when you start or deploy CAS via -DbaseDir=/my/directory.
• If you need the full stacktrace output of the exceptions, you can define the system property -Dlog.file.stacktraces=true for the runtime when you start or deploy CAS.
• If you need to change CAS logging levels, you can define the system property -Dcas.log.level=debug for the runtime when you start or deploy CAS. This will generally affect all log messages that would be submitted via components from the org.apereo.cas namespace, including all sub-packages and components.

If you prefer to control the logging levels a bit more forcefully and dynamically, you can define the log level for the package you prefer when you start and run CAS particularly with an embedded servlet container:

java -jar build/libs/cas.war --logging.level.org.apereo.cas=debug

Or alternatively, you could define the same setting in your cas.properties, though note that this technique only affects log messages once the CAS configuration file has been loaded and processed by the runtime:

logging.level.org.apereo.cas=debug

These options work for all packages and components, regardless of whether they’re owned or developed by CAS.

LDAP Authentication

We need to first establish a primary mode of validating credentials by sticking with LDAP authentication. The strategy here, as indicated by the CAS documentation, is to declare the intention/module in the build script:

implemntation "org.apereo.cas:cas-server-support-ldap"

…and then configure the relevant cas.authn.ldap[x] settings for the directory server in use. Most commonly, that would translate into the following settings:

cas.authn.ldap[0].type=AUTHENTICATED
cas.authn.ldap[0].ldap-url=ldaps://ldap1.example.org
cas.authn.ldap[0].base-dn=dc=example,dc=org
cas.authn.ldap[0].search-filter=cn={user}
cas.authn.ldap[0].bind-dn=cn=Directory Manager,dc=example,dc=org
cas.authn.ldap[0].bind-credential=...

To resolve and fetch the needed attributes which will be used later by CAS for release, the simplest way would be to let LDAP authentication retrieve the attributes directly from the directory server. The following setting allows us to do just that:

cas.authn.ldap[0].principal-attribute-list=memberOf,cn,givenName,mail

Registering Applications

Client applications that wish to use the CAS server for authentication must be registered with the server apriori. CAS provides several facilities to keep track of the registration records and you may choose any that fits your needs best. In more technical terms, CAS deals with service management using two specific components: Individual implementations that support a form of a database are referred to as Service Registry components and they are many. There is also a parent component that sits on top of the configured service registry as more of an orchestrator that provides a generic facade and entry point for the rest of CAS without entangling all other operations and subsystems with the specifics and particulars of storage technology.

In this tutorial, we are going to try to configure CAS with the JSON service registry.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-json-service-registry"

Next, you must teach CAS how to look up JSON files to read and write registration records. This is done in the cas.properties file:

cas.service-registry.core.init-from-json=false
cas.service-registry.json.location=file:/etc/cas/services

…where a sample ApplicationName-1001.json would then be placed inside /etc/cas/services:

{
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "https://app.example.org",
  "name" : "ApplicationName",
  "id" : 1001
}

Or perhaps a slightly more advanced version would be an application definition that allows for the release of certain attributes that we previously retrieved from LDAP as part of authentication:

{
  "@class" : "org.apereo.cas.services.CasRegisteredService",
  "serviceId" : "https://app.example.org",
  "name" : "ApplicationName",
  "id" : 1001,
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllowedAttributeReleasePolicy",
    "allowedAttributes" : [ "java.util.ArrayList", [ "cn", "mail" ] ]
  }
}

Ticketing

A robust CAS deployment requires the presence and configuration of an internal database that is responsible for keeping track of tickets issued by CAS. CAS itself comes by default with a memory-based node-specific cache that is often more than sufficient for smaller deployments or certain variations of a clustered deployment. Just like the service management facility, a large variety of databases and storage options are supported by CAS under the facade of a Ticket Registry.

In this tutorial, we are going to configure CAS to use a Hazelcast Ticket Registry with the assumption that our deployment is going to be deployed in an AWS-sponsored environment. Hazelcast Ticket Registry is often a decent choice when deploying CAS in a cluster and can take advantage of AWS’s native support for Hazelcast to read node metadata properly and locate other CAS nodes in the same cluster to present a common, global and shared ticket registry. This is an ideal choice that requires very little manual work and/or troubleshooting, compared to using options such as Multicast or manually noting down the address and location of each CAS server in the cluster.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-hazelcast-ticket-registry"

Next, the AWS-specific configuration of Hazelcast would go into our cas.properties:

cas.ticket.registry.hazelcast.cluster.discovery.enabled=true
cas.ticket.registry.hazelcast.cluster.discovery.aws.access-key=...
cas.ticket.registry.hazelcast.cluster.discovery.aws.secret-key=...
cas.ticket.registry.hazelcast.cluster.discovery.aws.region=us-east-1
cas.ticket.registry.hazelcast.cluster.discovery.aws.security-group-name=...
# cas.ticket.registry.hazelcast.cluster.discovery.aws.tag-key=
# cas.ticket.registry.hazelcast.cluster.discovery.aws.tag-value=

That should do it.

Of course, if you are working on a more modest CAS deployment in an environment that is more or less owned by you and you prefer more explicit control over CAS node registrations in your cluster, the following settings would be more ideal:

# cas.ticket.registry.hazelcast.cluster.instance-name=localhost
# cas.ticket.registry.hazelcast.cluster.network.port=5701
# cas.ticket.registry.hazelcast.cluster.network.port-auto-increment=true
cas.ticket.registry.hazelcast.cluster.network.members=123.321.123.321,223.621.123.521,...

Audit Logs

CAS provides a facility for auditing authentication activity, allowing them to be recorded to a variety of storage services. Essentially, audited authentication events attempt to provide the who, what, when, how, along with any additional contextual information that might be useful to track activity. By default, auditable records are sent to the CAS log file and they may look like this:

WHO: casuser
WHAT: supplied credentials: ...
ACTION: AUTHENTICATION_SUCCESS
APPLICATION: CAS
WHEN: Mon Aug 26 12:35:59 IST 2013
CLIENT IP ADDRESS: 172.16.5.181
SERVER IP ADDRESS: 192.168.200.22

It’s often useful to track audit records in a relational database for future monitoring, data mining and querying features that may be done outside CAS. Here, we try to configure CAS to push audit data into a PostgreSQL database.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

dependencies {
  implementation "org.apereo.cas:cas-server-support-audit-jdbc"
}

Then, put specific audit settings in cas.properties:

cas.audit.jdbc.user=postgres
cas.audit.jdbc.password=password
cas.audit.jdbc.driver-class=org.postgresql.Driver
cas.audit.jdbc.url=jdbc:postgresql://localhost:5432/audit
cas.audit.jdbc.dialect=org.hibernate.dialect.PostgreSQL10Dialect

You may also note that the audit record includes a special field for Client IP Address, which typically notes the IP address of the end-user attempting to authenticate, etc. Deployments that are behind a proxy or a load balancer often tend to mask the real IP address by default, and expose it using a dedicated header, such as X-Forwarded-For. This can be configured with CAS as well, so the correct IP is then recorded into the audit log:

cas.audit.engine.alternate-client-addr-header-name=X-Forwarded-For

Multifactor Authentication via Duo Security

As a rather common use case, the majority of CAS deployments that intend to turn on multifactor authentication support tend to do so via Duo Security. We will be going through the same exercise here where we let CAS trigger Duo Security for users who belong to the mfa-eligible group, indicated by the memberOf attribute on the LDAP user account.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-duo"

Then, put specific Duo Security settings in cas.properties. Things such as the secret key, integration key, etc which should be provided by your Duo Security subscription:

cas.authn.mfa.duo[0].duo-secret-key=
cas.authn.mfa.duo[0].duo-integration-key=
cas.authn.mfa.duo[0].duo-api-host=

At this point, we have enabled Duo Security and we just need to find a way to instruct CAS to route the authentication flow over to Duo Security in the appropriate condition. Our task here is to build a special condition that activates multifactor authentication if any of the values assigned to the attribute memberOf contain the value mfa-eligible. This condition is placed in the cas.properties file:

cas.authn.mfa.triggers.principal.global-principal-attribute-name-triggers=memberOf
cas.authn.mfa.triggers.principal.global-principal-attribute-value-regex=mfa-eligible

If the above condition holds true and CAS is to route to a multifactor authentication flow, that would be one supported and provided by Duo Security since that’s the only provider that is currently configured to CAS.

OpenID Connect

We can also turn on support for the OpenID Connect protocol, allowing CAS to act as an OP (OpenID Connect Provider). OpenId Connect is a continuation of the OAuth protocol with some additional variations. If you enable OpenId Connect, you will have automatically enabled OAuth as well. “Two birds for one stone” sort of thing, though no disrespect to the avian community!

By turning on support for OpenID Connect, CAS begins to act as an authorization server, allowing client applications to verify the identity of the end-user and to obtain basic profile information in an interoperable and REST-like manner. For this tutorial, our focus is to mainly on integrating web-based client applications using the Authorization Code flow of OpenID Connect, which is quite similar to the CAS protocol; you receive a code, you validate the code and receive an access token as well as an ID token.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-oidc"

Then, we teach CAS about specific aspects of the authorization server functionality:

cas.authn.oidc.core.issuer=https://sso.example.org/cas/oidc
cas.authn.oidc.jwks.file-system.jwks-file=file:///etc/cas/config/keystore.jwks

The JWKS resource is used by CAS to create (or use an existing) JSON web keystore composed of private and public keys that enable clients to validate a JSON Web Token (JWT) such as an id token, issued by CAS as an OpenID Connect Provider. Here, we define the global keystore as a path on the file system.

That should be all. Now, you can proceed to register your client web application with CAS similar to the approach described earlier:

{
  "@class" : "org.apereo.cas.services.OidcRegisteredService",
  "clientId": "my-client-id",
  "clientSecret": "my-client-secret",
  "serviceId" : "^https://my.application.com/oidc/.+",
  "name": "OIDC",
  "description": "A sample OIDC client application"
  "id": 1
}

SAML2

We can also turn on support for the SAML2 protocol, allowing CAS to act as a SAML2 identity provider. By turning on support for SAML2, CAS begins to accept SAML2 authentication requests and will in the end produce SAML2 assertions and responses. In doing so, CAS will also generate its own SAML2 identity provider metadata along with other needed artifacts and certificates, all of which should immediately get you started with service provider registrations.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-saml-idp"

Then, we need to decide what our SAML2 entity id should be and where to keep our SAML2 metadata. To keep matters simple, we’ll choose the filesystem to track and store metadata and its artifacts:

cas.authn.saml-idp.core.entity-id=https://cas.apereo.org/saml/idp,
cas.authn.saml-idp.metadata.file-system.location=file:///path/to/metadata/directory

An entity id is a globally unique name for your identity provider. It’s used to identify the IdP during SAML transactions. It is typically a URI, although it doesn’t have to point to an actual resource. It’s often set to the IdP’s base URL or a specific URL that describes the entity. For example, it could be something like https://cas.apereo.org/saml/idp. This id is included in the metadata that CAS shares with its partners, and it’s used in SAML messages to indicate the sender or the intended recipient. It’s important that the entity id is unique to avoid confusion or conflicts.

Metadata is an XML document that contains information about a SAML entity, such as an Identity Provider (IdP) or a Service Provider (SP). This metadata is used to facilitate the exchange of information for SAML transactions.

The metadata typically includes:

• Entity ID: A unique identifier for the entity.
• Endpoints: URLs where the entity sends or receives SAML messages. These include Assertion Consumer Service (ACS) endpoints, Single Logout Service (SLS) endpoints, etc.
• Certificates: Public key certificates used for signing and/or encrypting SAML assertions.
• Binding: The protocol binding that the entity supports (e.g., HTTP-Redirect, HTTP-POST, etc.). The metadata is usually exchanged out-of-band (i.e., not through the SAML protocol itself) and is often made available at a publicly accessible URL. This allows partners to fetch and refresh the metadata as needed. For CAS, this typically would be: https://sso.example.org/cas/idp/metadata

Now, you can proceed to register your client web application with CAS similar to the approach described earlier:

{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-for-saml2-service-provider",
  "name" : "Sample",
  "id" : 1,
  "metadataLocation" : "https://saml2.example.org/sp/metadata",
  "attributeReleasePolicy" : {
    "@class" : "org.apereo.cas.services.ReturnAllAttributeReleasePolicy"
  }
}

Proxy/External Authentication

We can also turn on support for external/delegated authentication, to hand the authentication off to an external identity provider and allow CAS to act as proxy in between. In the most common use case, CAS is made entirely invisible to the end-user such that the redirect to the external identity provider simply happens automatically and as far as the audience is concerned, there are only the external identity provider and the target application that is, of course, prepped to speak to the CAS server.

Configuration

The initial setup is in fact simple; as the documentation describes you need to add the required dependency in your overlay:

implementation "org.apereo.cas:cas-server-support-pac4j-saml"

…and then in your cas.properties, instruct CAS to hand off authentication to the, in this case, SAML2 identity provider:

cas.authn.pac4j.saml[0].keystore-password=pac4j-demo-passwd
cas.authn.pac4j.saml[0].private-key-password=pac4j-demo-passwd
cas.authn.pac4j.saml[0].service-provider-entity-id=cas:apereo:pac4j:saml
cas.authn.pac4j.saml[0].service-provider-metadata-path=/etc/cas/config/sp-metadata.xml
cas.authn.pac4j.saml[0].keystore-path=$/path/to/samlKeystore.jks
cas.authn.pac4j.saml[0].identity-provider-metadata-path=https://idp.example.org/metadata.php
cas.authn.pac4j.saml[0].destination-binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
cas.authn.pac4j.saml[0].client-name=SAML2Client

The above settings instruct CAS to:

• Generate the service-provider metadata at /etc/cas/config/sp-metadata.xml using entity id urn:mace:saml:pac4j.org automatically. This metadata is created on CAS startup once the login page is rendered. This metadata is expected to be shared somehow with the SAML2 identity provider.
• The URL to the identity provider metadata is also taught to CAS; note that in this case, we are using Okta as the SAML2 external identity provider.

Likewise, if you need to configure an exteral identity provider via the OpenID Connect protocol, the following settings would be more or less appropriate:

cas.authn.pac4j.oidc[0].generic.id=...
cas.authn.pac4j.oidc[0].generic.secret=...
cas.authn.pac4j.oidc[0].generic.client-name=Keycloak
cas.authn.pac4j.oidc[0].generic.discovery-uri=https://ext.idp.org/.well-known/openid-configuration

Be sure to include the following dependency as well in your build:

implementation "org.apereo.cas:cas-server-support-pac4j-oidc"

Monitoring & Status

Many CAS deployments rely on the /status endpoint for monitoring the health and activity of the CAS deployment. This endpoint is typically secured via an IP address, allowing external monitoring tools and load balancers to reach the endpoint and parse the output. In this quick exercise, we are going to accomplish that task, allowing the status endpoint to be available over HTTP to localhost.

Configuration

First, ensure you have declared the appropriate module/intention in the build:

implementation "org.apereo.cas:cas-server-support-monitor"

To enable and expose the status endpoint, the following settings should come in handy:

management.endpoints.web.base-path=/actuator
management.endpoints.web.exposure.include=status
management.endpoint.status.enabled=true

cas.monitor.endpoints.endpoint.status.access=IP_ADDRESS
cas.monitor.endpoints.endpoint.status.required-ip-addresses=127.0.0.1

Remember that the default path for endpoints exposed over the web is at /actuator, such as /actuator/status.

Overlay Customization

The build/libs directory contains the results of the overlay process. Since I have not actually customized and overlaid anything yet, all configuration files simply match their default and are packaged as such. As an example, let’s grab the default message bundle and change the text associated with screen.welcome.instructions.

First, I will need to move the file to my project directory so that during the overlay process Gradle can use that instead of what is provided by default.

Here we go:

./gradlew getResource -PresourceName=messages.properties

Then I’ll leave everything in that file alone, except the line I want to change.

...
screen.welcome.instructions=Speak friend and enter.
...

Then I’ll package things up as usual.

./gradlew clean build

If I explode the built web application again and look at build/cas/WEB-INF/classes/messages.properties after the build, I should see that the overlay process has picked and overlaid onto the default my version of the file.

User Interface Customizations

To modify the CAS HTML views, each file first needs to be brought over into the overlay. You can use the ./gradlew listTemplateViews command to see what HTML views are available for customizations. Once chosen, simply use ./gradlew getResource -PresourceName=footer.html to bring the view into your overlay. Once you have the footer.html brought into the overlay, you can simply modify the file at src/main/resources/templates/fragments/footer.html, and then repackage and run the build as usual.

Deploy

You have several options when it comes to deploying the final cas.war file. The easiest approach would be to simply use the ./gradlew run command and have the overlay be deployed inside an embedded container. By default, the CAS web application expects to run on the secure port 8443 which requires that you create a keystore file at /etc/cas/ named thekeystore.

Deploy Behind a Proxy

Using the embedded Apache Tomcat container provided by CAS automatically is the recommended approach in almost all cases (The embedded bit; not the Apache Tomcat bit) as the container configuration is entirely automated by CAS and its version is guaranteed to be compatible with the running CAS deployment. Furthermore, updates and maintenance of the servlet container are handled at the CAS project level where you as the adopter are only tasked with making sure your deployment is running the latest available release to take advantage of such updates.

If you wish to run CAS via the embedded Apache Tomcat container behind a proxy or load balancer and have that entity terminate SSL, you will need to open up a communication channel between the proxy and CAS such that (as an example):

• Apache Tomcat runs on port 8080, assuming that’s what the proxy uses to talk to CAS.
• Apache Tomcat has SSL turned off.
• Apache Tomcat connector listening on the above port is marked as secure.

The above task list translates to the following properties expected to be found in your cas.properties:

server.port=8080
server.ssl.enabled=false
cas.server.tomcat.http.enabled=false
cas.server.tomcat.http-proxy.enabled=true
cas.server.tomcat.http-proxy.secure=true
cas.server.tomcat.http-proxy.scheme=https

Deploy via Docker

The overlay embraces the Jib Gradle Plugin to provide easy-to-use out-of-the-box tooling for building CAS docker images. Jib is an open-source Java containerizer from Google that handles all the steps of packaging CAS into a container image. It does not require you to write a Dockerfile and it is directly integrated into the overlay.

Building a CAS docker image via jib is as simple as:

./gradlew build jibDockerBuild

If you prefer a more traditional approach, there is always:

./gradlew build
docker-compose build

You may also build Docker images using the Spring Boot Gradle plugin.

Deploy via Embedded Container

If the WAR overlay is prepped with an embedded servlet container such as Apache Tomcat, then you may run the CAS web application directly and once built, using:

java -jar build/libs/cas.war

The choice of the embedded servlet container is noted by the appServer property found in the gradle.properties file:

# Use -tomcat, -jetty, -undertow for deployment to other embedded containers
# if the overlay application supports or provides the chosen type.
# You should set this to blank if you want to deploy to an external container.
# and want to set up, download, and manage the container (i.e. Apache Tomcat) yourself.
appServer=-tomcat

All servlet containers presented here, embedded or otherwise, aim to be production-ready. This means that CAS ships with useful defaults out of the box that may be overridden, if necessary and by default, CAS configures everything for you from development to production in today’s platforms. In terms of their production quality, there is almost no difference between using an embedded container vs. an external one.

Unless there are specific, technical, and reasonable objections, choosing an embedded servlet container is almost always the better choice.

If you forget to specify the correct servlet container type and yet choose to run CAS directly, it is likely that you would receive the following error:

ERROR [org.springframework.boot.SpringApplication] - <Application run failed>
  org.springframework.context.ApplicationContextException: Unable to start web server;
    nested exception is org.springframework.context.ApplicationContextException: 
    Unable to start ServletWebServerApplicationContext due to missing ServletWebServerFactory bean.

Gradle Tasks

The Gradle WAR overlay provides many additional commands that might prove helpful for troubleshooting purposes:

# Run the CAS web application in standalone executable mode
./gradlew executable

# Debug the CAS web application in embedded mode on port 5005
./gradlew debug

# Run the CAS web application in embedded container mode
./gradlew run

# Display the CAS version
./gradlew casVersion

# Export collection of CAS properties
./gradlew exportConfigMetadata

The exportConfigMetadata task can be quite useful as it produces a comprehensive catalog of all CAS settings that one could potentially use, along with documentation for each setting, default values, and more.

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 the content here 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. If you have suggestions or ideas on how to improve this post, please feel free to reach out to us.

Misagh Moayyed