Apereo CAS - Spring Boot Admin Integration


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

Spring Boot Admin is a community project to manage and monitor Spring Boot applications such as Apereo CAS. The admin server presents an AngularJS-based UI that interacts with the actuator endpoints provided by Spring Boot in CAS. One CAS has registered itself with the admin server, either using the Spring Admin Client via HTTP or as part of discovery using technologies such as Eureka, Consul, etc, the admin server can begin to provide feature to monitor CAS for health status, JVM & memory metrics, environment settings, thread dumps, audit data, logs, etc.

While the CAS integration with the Spring Boot Admin server has been available for some time (likely since CAS 5.1.x), in this tutorial we will focus on how to get the latest version of Apereo CAS integrated with the Admin server. At a high-level, we need to accomplish the following:

  • Deploy and configure the Spring Boot Admin server
  • Configure CAS to register with the Spring Boot Admin server

Our starting position is based on the following:

Spring Boot Admin Server Configuration

The Spring Boot Admin server runs a standalone Spring Boot application on its own with a setup that is very similar to the CAS server itself. There is a WAR overlay that can be used to configure and deploy the server. Once you clone the Admin overlay project, you may need to create a src/main/resources/application.properties to control the behavior of the Admin server. By default, the application runs on port 8444 and does require SSL with a keystore that is expected at file:/etc/cas/thekeystore. The default settings should match the following:

server.port=8444

server.ssl.key-store=file:/etc/cas/thekeystore
server.ssl.key-store-password=changeit
server.ssl.key-password=changeit

# Protect the boot-admin endpoints for basic/form authn
spring.security.user.name=casuser
spring.security.user.password=e3f98098-edb5-4217-9dcb-ad04999a8794

Given the Admin server itself is based on top of Spring Boot, all relevant Spring Boot settings here do also apply to control the general behavior of the web application. There are also many other settings available to tweak the behavior of the Admin server functionality itself. For a more comprehensive list, please see the Spring Boot Admin documentation.

Once you’re ready, execute the following:

./build.sh run

…at which point a successful startup attempt would demonstrate the following in the logs:

INFO [org.apereo.cas.CasSpringBootAdminServerWebApplication] - <No active profile set, falling back to default profiles: default>
...
INFO [org.springframework.boot.web.embedded.tomcat.TomcatWebServer] - <Tomcat started on port(s): 8444 (https) with context path ''>
...
INFO [org.apereo.cas.CasSpringBootAdminServerWebApplication] - <Started CasSpringBootAdminServerWebApplication in 20.798

…which allows you to navigate to Admin server in your browser at https://admin.example.org:8444:

image

There is nothing registered with the Admin server yet. As the next step, we will connect our CAS server to the Admin server.

CAS Server Configuration

Each individual CAS server is given the ability to auto-register itself with the Admin server. This is done using the following module that should go into the CAS overlay:

compile "org.apereo.cas:cas-server-support-bootadmin-client:${project.'cas.version'}"

Of course, we need to teach CAS about our Admin server using the cas.properties file:

spring.boot.admin.client.enabled=true
spring.boot.admin.client.url=https://admin.example.org:8444
spring.boot.admin.client.instance.management-base-url=https://sso.example.org/cas

So, our CAS server is running on https://sso.example.org/cas which presents a number of actuator endpoints that are used by the Admin server to monitor status and report results. Therefore, we will need to enable the endpoints in CAS in cas.properties so they may be consumable by the Admin server:

management.endpoints.enabled-by-default=true
management.endpoints.web.exposure.include=*

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

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

These settings are primarily offered and controlled by Spring Boot and accomplish the following:

  • Enable all actuator endpoints by default.
  • Expose all actuator endpoints over the web via http.
  • Secure all actuator endpoints using basic authentication where the master credentials are casuser and Mellon.
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.

To verify, you can try to hit a few of the endpoints to see the behavior in action:

curl -u casuser:Mellon -k https://sso.example.org/cas/actuator/status | jq

…where you get back:

{
  "status": 200,
  "description": "OK",
  "health": "UP",
  "host": "misaghmoayyed",
  "server": "https://sso.example.org/cas",
  "version": "6.0.0-RC3 - ..."
}

You can also try hitting actuator/health, actuator/info and many others.

Now that are endpoints are enabled and secured, we need to configure CAS to use our security credentials when contacting the Admin server as well:

spring.boot.admin.client.instance.metadata.user.name=casuser
spring.boot.admin.client.instance.metadata.user.password=Mellon

# In case Spring Boot Admin endpoints are protected via basic authn
spring.boot.admin.client.username=casuser
spring.boot.admin.client.password=e3f98098-edb5-4217-9dcb-ad04999a8794
WATCH OUT!
While the actuator endpoints in CAS are protected in some fashion, the endpoints of the Spring Boot Admin server that are responsible for handling registration requests and more are not by default protected using the existing overlay. This is an item that will likely get worked out before the final CAS release.</a>.

When you build and deploy CAS next, the Admin server should properly recognize the registration request and display something like this:

image

…where you can drill into the app and look at various screens and monitoring activity. For example, check out the available http web mappings and URLs:

image

…or logging configuration:

image

There is a lot more you can do with the Admin server to add security, custom notifications, etc. Please see the Spring Boot Admin documentation.

Finale

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.0.0 RC4 Feature Release

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

Apereo CAS 6.0.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.0.x Deployment - WAR Overlays

Learn how to configure and build your own CAS deployment via the WAR overlay method, get rich quickly, stay healthy indefinitely and respect family and friends in a few very easy steps.

Apereo CAS - Jib at CAS Docker Images

Learn how you may use Jib, an open-source Java containerizer from Google, and its Gradle plugin to build CAS docker images seamlessly without stepping too deep into scripting Dockerfile commands.

Apereo CAS 6 - Administrative Endpoints & Monitoring

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

Apereo CAS - SAML2 Metadata with MongoDb

CAS distributed SAML2 metadata management using MongoDB, where you learn how to store metadata documents inside MongoDB for CAS as a SAML2 identity provider and all other registered SAML2 service providers.

Apereo CAS - Slurp Configuration with Groovy

Learn how CAS configuration may be consumed via Groovy to simplify and consolidate settings for multiple deployment environments and profiles.

Apereo CAS - Configuration Management with MongoDb

CAS distributed configuration management using MongoDb, where you learn how to store and secure CAS configuration settings and properties inside MongoDb.

Apereo CAS - Integration with HashiCorp Vault

CAS distributed configuration management using HashCorp Vault, where you learn how to store and secure CAS configuration settings and properties inside Vault.

CAS 6.0.0 RC3 Feature Release

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