Apereo CAS 6 - Administrative Endpoints & Monitoring


Collaborate
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.

CAS, being a Spring-Boot application at heart, includes a number of endpoints to help you monitor and manage the server when it’s pushed to production. You can choose to manage and monitor the deployment using HTTP endpoints, referred to as actuators. This tutorial provides a basic overview of the endpoints provided by both Spring Boot and CAS and also provides instructions on how such endpoints can be secured for access and win.

Our starting position is based on the following:

Actua…What?

In essence, actuator endpoints bring production-ready features to CAS. Monitoring a running CAS instance, gathering metrics, understanding traffic or the state of our database becomes trivial with such endpoints. The main benefit of these endpoints is that we can get production grade tools without having to actually implement these features ourselves. Actuators are mainly used to expose operational information about the running application – health, metrics, info, dump, env, etc. These are HTTP endpoints or JMX beans to enable us to interact with it.

Definition
An actuator is a manufacturing term, referring to a mechanical device for moving or controlling something. Actuators can generate a large amount of motion from a small change.

The full list of endpoints provided to your CAS deployment is posted here. Note that you do not need to do anything extra special to get these endpoints added to your deployment; these are all available by default and just need to be turned on and secured for access.

Endpoints

Starting with Spring Boot 2 and CAS 6.0.x, the actuator endpoints and their method of security are entirely revamped. Here are the main differences:

  • Endpoints can individually be exposed over the web under HTTP.
  • Security of each endpoint using the combo of enabled and sensitive is now gone, and each endpoint entirely embraces Spring Security for protection.
  • Endpoints internally are marked as @Endpoint and can be standalone or extensions of existing endpoints such as /health.
  • Enabling an endpoint may pass through several layers of security: Default setting if undefined, globally or per endpoint.

Examples

Let’s go through a number of scenarios that might be helpful. Bear in mind that in order to work with an endpoint, you must go through the following steps:

  • The endpoint must be enabled.
  • The endpoint may be somehow exposed.
  • The endpoint may be somehow secured.

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

Example 1

Expose the CAS status endpoint over the web, enable it and make sure its protected via basic authentication:

management.endpoints.web.exposure.include=status
management.endpoint.status.enabled=true

cas.monitor.endpoints.endpoint.status.access=AUTHENTICATED

spring.security.user.name=casuser
spring.security.user.password=Mellon

Example 2

Expose the CAS status endpoint over the web, enable it and make sure a list of IP addresses can reach it:

management.endpoints.web.exposure.include=status
management.endpoint.status.enabled=true
cas.monitor.endpoints.endpoint.status.access=IP_ADDRESS
cas.monitor.endpoints.endpoint.status.requiredIpAddresses=1.2.3.4,0.0.0.0

Example 3

Expose the Spring Boot health and info endpoints over the web, enable them and make sure access to health is secured via basic authentication:

management.endpoints.web.exposure.include=health,info

management.endpoint.health.enabled=true
management.endpoint.health.show-details=always

management.endpoint.info.enabled=true

cas.monitor.endpoints.endpoint.health.access=AUTHENTICATED
cas.monitor.endpoints.endpoint.info.access=ANONYMOUS

spring.security.user.name=casuser
spring.security.user.password=Mellon

Example 4

Enable and expose all endpoints with no regard for security:

management.endpoints.web.exposure.include=*
management.endpoints.enabled-by-default=true
cas.monitor.endpoints.endpoint.defaults.access=ANONYMOUS
WATCH OUT!
The above collection of settings MUST only be used for demo purposes and serve as an EXAMPLE. It is not wise to enable and expose all actuator endpoints to the web and certainly, the security of the exposed endpoints should be taken into account very seriously. None of the CAS or Spring Boot actuator endpoints are enabled by default. For production, you should carefully choose which endpoints to expose.

Example 5

In addition to the usual, let’s remap the path to endpoints to start with endpoints instead of actuator, and lets rename the status endpoint to be heartbeat:

management.endpoints.web.path-mapping.status=heartbeat
management.endpoints.web.base-path=/endpoints
management.endpoints.web.exposure.include=status
management.endpoint.status.enabled=true
cas.monitor.endpoints.endpoint.status.access=IP_ADDRESS
cas.monitor.endpoints.endpoint.status.requiredIpAddresses=1.2.3.4

Dashboard

Note that all GUIs related to CAS endpoints are removed and will be slightly transitioned over to the CAS Management Web Application. However, while the screens may be gone the underlying functionality remains all the same. For example, provided the endpoint is correctly enabled and secured you can invoke the statistics endpoint to get the required data:

curl -k https://sso.example.org/cas/actuator/statistics | jq

…where you’d see something like this:

{
  "upTime": 64,
  "totalMemory": "1 GB",
  "expiredTgts": 0,
  "expiredSts": 0,
  "maxMemory": "4 GB",
  "freeMemory": "615 MB",
  "unexpiredTgts": 0,
  "unexpiredSts": 0
}

Over time, this data should become accessible via the management application. Remember that for endpoints which are native to and provided by Spring Boot, you may always try the Spring Boot Admin Server.

So…

It’s important that you start off simple and make changes one step at a time. Once you have a functional environment, you can gradually and slowly add customizations to move files around.

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.

Misagh Moayyed

Related Posts

CAS 6.1.0 RC3 Feature Release

...in which I present an overview of CAS 6.1.0 RC3 release.

Apereo CAS 6.1.x - Credential Caching & Proxy AuthN

Learn how you may configure Apereo CAS to capture and cache the credential's password and the proxy-granting ticket in proxy authentication scenarios, pass them along to applications as regular attributes/claims. We will also be reviewing a handful of attribute release strategies that specifically affect authentication attributes, conveying metadata about the authentication event itself.

Apereo CAS 6.1.x - Attribute Repositories w/ Person Directory

An overview of CAS attribute repositories and strategies on how to fetch attributes from a variety of sources in addition to the authentication source, merge and combine attributes from said sources to ultimately release them to applications with a fair bit of caching.

Apereo CAS 6.1.x - Building CAS Feature Modules

An overview of how various CAS features modules today can be changed and tested from the perspective of a CAS contributor working on the codebase itself to handle a feature request, bug fix, etc.

CAS 6.1.0 RC2 Feature Release

...in which I present an overview of CAS 6.1.0 RC2 release.

Apereo CAS - Riffing on Attribute Release Policies

Learn how to release the kraken of attributes to CAS clients, relying parties and service providers using a variety of attribute release policies and authentication protocols, sampled and collected here to fun and profit.

Apereo CAS - Delegated Authentication to SAML2 Identity Providers

Learn how your Apereo CAS deployment may be configured to delegate authentication to an external SAML2 identity provider.

Apereo CAS - Custom Login Fields w/ Dynamic Bindings

Learn how to extend the Spring Webflow model to add custom fields to the CAS login form and the authentication process and take advantage of the additional user-provided data in customized authentication handlers.

Apereo CAS as an OAuth2 Authorization Server

Learn how to configure CAS as an OAuth2 Authorization Server and configure Spring Boot client app to work with it

Apereo CAS - SAML2 Identity Provider Integration w/ Gitlab (also staring HAProxy and LDAP)

Learn how Apereo CAS may act as a SAML2 identity provider for Gitlab and run everything locally on a workstation with Docker and Java.