Course – LSS – NPI (cat=Spring Security)
announcement - icon

If you're working on a Spring Security (and especially an OAuth) implementation, definitely have a look at the Learn Spring Security course:


1. Overview

In this tutorial, we’ll be looking at the Apereo Central Authentication Service (CAS) and we’ll see how a Spring Boot service can use it for authentication. CAS is an enterprise Single Sign-On (SSO) solution that is also open source.

What is SSO? When you log in to YouTube, Gmail and Maps with the same credentials, that’s Single Sign-On. We’re going to demonstrate this by setting up a CAS server and a Spring Boot app. The Spring Boot app will use CAS for authentication.

2. CAS Server Setup

2.1. CAS Installation and Dependencies

The server uses the Maven (Gradle) War Overlay style to ease setup and deployment:

git clone cas-server

This command will clone the cas-overlay-template into the cas-server directory.

Some of the aspects we’ll be covering include JSON service registration and JDBC database connection. So, we’ll add their modules to the dependencies section of build.gradle file:

compile "org.apereo.cas:cas-server-support-json-service-registry:${casServerVersion}"
compile "org.apereo.cas:cas-server-support-jdbc:${casServerVersion}"

Let’s make sure to check the latest version of casServer.

2.2. CAS Server Configuration

Before we can start the CAS server, we need to add some basic configurations. Let’s start by creating a cas-server/src/main/resources folder and in this folder. This will be followed by the creation of in the folder, too:


Let’s proceed with the creation of the key-store file referenced in the configuration above. First, we need to create the folders /etc/cas and /etc/cas/config in cas-server/src/main/resources.

Then, we need to change the directory to cas-server/src/main/resources/etc/cas and run the command to generate thekeystore:

keytool -genkey -keyalg RSA -alias thekeystore -keystore thekeystore -storepass changeit -validity 360 -keysize 2048

In order for us not to have an SSL handshake error, we should use localhost as the value of first and last name. We should use the same for the organisation name and unit as well. Furthermore, we need to import the thekeystore into the JDK/JRE we’ll be using to run our client app:

keytool -importkeystore -srckeystore thekeystore -destkeystore $JAVA11_HOME/jre/lib/security/cacerts

The password for the source and destination keystore is changeit. On Unix systems, we may have to run this command with admin (sudo) privilege. After importing, we should restart all instances of Java that’s running or restart the system.

We’re using JDK11 because it’s required by CAS version 6.1.x. Also, we defined the environment variable $JAVA11_HOME that points to its home directory. We can now start the CAS server:

./gradlew[.bat] run$JAVA11_HOME

When the application starts, we’ll see “READY” printed on the terminal and the server will be available at https://localhost:8443.

2.3. CAS Server User Configuration

We can’t log in yet as we’ve not configured any user. CAS has different methods of managing configuration, including the standalone mode. Let’s create a config folder cas-server/src/main/resources/etc/cas/config in which we’ll create a properties file Now, we can define a static user in the properties file:


We have to communicate the location of the config folder to CAS server for the settings to take effect. Let’s update tasks.gradle so we can pass the location as a JVM argument from the command line:

task run(group: "build", description: "Run the CAS web application in embedded container mode") {
    dependsOn 'build'
    doLast {
        def casRunArgs = new ArrayList<>(Arrays.asList(
          "-server -noverify -Xmx2048M -XX:+TieredCompilation -XX:TieredStopAtLevel=1".split(" ")))
        if (project.hasProperty('args')) {
        javaexec {
            main = "-jar"
            jvmArgs = casRunArgs
            args = ["build/libs/${casWebApplicationBinaryName}"]
   "Started ${commandLine}"

We then save the file and run:

./gradlew run$JAVA11_HOME

Please note that the value of cas.standalone.configurationDirectory is an absolute path. We can now go to https://localhost:8443 and log in with username casuser and password Mellon.

3. CAS Client Setup

We’ll use Spring Initializr to generate a Spring Boot client app. It’ll have Web, Security, Freemarker and DevTools dependencies. Besides, we’ll also add the dependency for Spring Security CAS module to its pom.xml:


Finally, let’s add the following Spring Boot properties to configure the app:


4. CAS Server Service Registration

Clients applications must register with the CAS server ahead of any authentication. CAS server supports the use of YAML, JSON, MongoDB and LDAP client registries.

In this tutorial, we’ll use the JSON Service Registry method. Let’s create yet another folder cas-server/src/main/resources/etc/cas/services. It’s this folder that’ll house the service registry JSON files.

We’ll create a JSON file that contains the definition of our client application. The name of the file, casSecuredApp-8900.json, follows the pattern serviceName-Id.json:

  "@class" : "",
  "serviceId" : "http://localhost:8900/login/cas",
  "name" : "casSecuredApp",
  "id" : 8900,
  "logoutType" : "BACK_CHANNEL",
  "logoutUrl" : "http://localhost:8900/exit/cas"

The serviceId attribute defines a regex URL pattern for the client application. The pattern should match the URL of the client application.

The id attribute should be unique. In other words, there shouldn’t be two or more services with the same id registered to the same CAS server. Having duplicate id will lead to conflicts and overriding of configurations.

We also configure the logout type to be BACK_CHANNEL and the URL to be http://localhost:8900/exit/cas so that we can do single logout later.
Before the CAS server can make use of our JSON configuration file, we have to enable the JSON registry in our

5. CAS Client Single Sign-On Configuration

The next step for us is to configure Spring Security to work with the CAS server. We should also check the full flow of interactions, called a CAS sequence.

Let’s add the following bean configurations to the CasSecuredApplication class of our Spring Boot app:

public CasAuthenticationFilter casAuthenticationFilter(
  AuthenticationManager authenticationManager,
  ServiceProperties serviceProperties) throws Exception {
    CasAuthenticationFilter filter = new CasAuthenticationFilter();
    return filter;

public ServiceProperties serviceProperties() {"service properties");
    ServiceProperties serviceProperties = new ServiceProperties();
    return serviceProperties;

public TicketValidator ticketValidator() {
    return new Cas30ServiceTicketValidator("https://localhost:8443");

public CasAuthenticationProvider casAuthenticationProvider(
  TicketValidator ticketValidator,
  ServiceProperties serviceProperties) {
    CasAuthenticationProvider provider = new CasAuthenticationProvider();
      s -> new User("[email protected]", "Mellon", true, true, true, true,
    return provider;

The ServiceProperties bean has the same URL as the serviceId in casSecuredApp-8900.json. This is important because it identifies this client to the CAS server.

The sendRenew property of ServiceProperties is set to false. This means a user only needs to present login credentials to the server once.

The AuthenticationEntryPoint bean will handle authentication exceptions. Thus, it’ll redirect the user to the login URL of the CAS server for authentication.

In summary, the authentication flow goes:

  1. A user attempts to access a secure page, which triggers an authentication exception
  2. The exception triggers AuthenticationEntryPoint. In response, the AuthenticationEntryPoint will take the user to the CAS server login page – https://localhost:8443/login
  3. On successful authentication, the server redirects back to the client with a ticket
  4. CasAuthenticationFilter will pick up the redirect and call CasAuthenticationProvider
  5. CasAuthenticationProvider will use TicketValidator to confirm the presented ticket on CAS server
  6. If the ticket is valid, the user will get a redirection to the requested secure URL

Finally, let’s configure HttpSecurity to secure some routes in WebSecurityConfig. In the process, we’ll also add the authentication entry point for exception handling:

protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests().antMatchers( "/secured", "/login").authenticated()
      .addFilterBefore(singleSignOutFilter, CasAuthenticationFilter.class)

6. CAS Client Single Logout Configuration

So far, we’ve dealt with single sign-on; let’s now consider CAS single logout (SLO).

Applications that use CAS for managing user authentication can log out a user from two places:

  • The client application can logout a user from itself locally – this will not affect the user’s login status in other applications using the same CAS server
  • The client application can also log out the user from the CAS server – this will cause the user to be logged out from all other client apps connected to the same CAS server.

We’ll first put in place logout on the client application and then extend it to single logout on the CAS server.

In order to make obvious what goes on behind the scene, we’ll create a logout() method to handle the local logout. On success, it’ll redirect us to a page with a link for single logout:

public String logout(
  HttpServletRequest request, 
  HttpServletResponse response, 
  SecurityContextLogoutHandler logoutHandler) {
    Authentication auth = SecurityContextHolder
    logoutHandler.logout(request, response, auth );
    new CookieClearingLogoutHandler(
      .logout(request, response, auth);
    return "auth/logout";

In the single logout process, the CAS server will first expire the user’s ticket and then send an async request to all registered client apps. Each client app that receives this signal will perform a local logout. Thereby accomplishing the goal of logout once, it will cause a log out everywhere.

Having said that, let’s add some bean configurations to our client app. Specifically, in the CasSecuredApplicaiton:

public SecurityContextLogoutHandler securityContextLogoutHandler() {
    return new SecurityContextLogoutHandler();

public LogoutFilter logoutFilter() {
    LogoutFilter logoutFilter = new LogoutFilter("https://localhost:8443/logout",
    return logoutFilter;

public SingleSignOutFilter singleSignOutFilter() {
    SingleSignOutFilter singleSignOutFilter = new SingleSignOutFilter();
    return singleSignOutFilter;

The logoutFilter will intercept requests to /logout/cas and redirect the application to the CAS server. The SingleSignOutFilter will intercept requests coming from the CAS server and perform the local logout.

7. Connecting the CAS Server to a Database

We can configure the CAS server to read credentials from a MySQL database. We’ll use the test database of a MySQL server that’s running in a local machine. Let’s update cas-server/src/main/resources/application.yml:

                sql: SELECT * FROM users WHERE email = ?
                url: jdbc:mysql://
                dialect: org.hibernate.dialect.MySQLDialect
                user: root
                password: root
                ddlAuto: none
                driverClass: com.mysql.cj.jdbc.Driver
                fieldPassword: password
                    type: NONE

Also, configure same in the cas-secured-app cas-secured-app/src/main/resources/

spring.datasource.url= jdbc:mysql://

We set the cas.authn.accept.users to blank. This will deactivate the use of static user repositories by the CAS server.

According to the SQL above, users’ credentials are stored in the users table. The email column is what represents the users’ principal (username).

Please make sure to check the list of supported databases, available drivers and dialects. We also set the password encoder type to NONE. Other encryption mechanisms and their peculiar properties are also available.

Note that the user in the database of the CAS server must be the same as that of the client application.

Let’s update CasAuthenticationProvider to have the same username as the CAS server:

public CasUserDetailsService getUser(){
    return new CasUserDetailsService();

public CasAuthenticationProvider casAuthenticationProvider(
  TicketValidator ticketValidator,
  ServiceProperties serviceProperties) {
    CasAuthenticationProvider provider = new CasAuthenticationProvider();
    return provider;
The CasAuthenticationProvider requires a UserDetailsService to load user details based on the CAS ticket. The UserDetailsService is responsible for retrieving user information from a data source, such as a database. In the loadUserByUsername method of the UserDetailsService implementation, you can customize the logic to load user details based on the provided username.
public class CasUserDetailsService implements UserDetailsService {

    private UserRepository userRepository;

    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        // Get the user from the database.
        CasUser casUser = getUserFromDatabase(username);

        // Create a UserDetails object.
        UserDetails userDetails = new User(
           Collections.singletonList(new SimpleGrantedAuthority("ROLE_ADMIN")));

        return userDetails;

    private CasUser getUserFromDatabase(String username) {
       return userRepository.findByEmail(username);

The loadUserByUsername method is a part of the CasUserDetailsService class. This method is responsible for loading a user’s details based on their username. You can find more information regarding Authentication with a Database-backed UserDetailsService.

Once the CAS ticket is validated and the user details are loaded, the CasAuthenticationProvider creates an authenticated Authentication object, which can then be used for authorization and access control in the application.

CasAuthenticationProvider does not use the password for authentication. Nonetheless, its username has to match that of the CAS server for authentication to be successful. CAS server requires a MySQL server to be running on localhost at port 3306. The username and password should be root.

Restart the CAS server and the Spring Boot app once again. Then use the new credentials for authentication.

8. Conclusion

We have looked at how to use CAS SSO with Spring Security and many of the configuration files involved. There are many other aspects of CAS SSO that is configurable. Ranging from themes and protocol types to authentication policies.

These and others are in the docs. The source code for the CAS server and the Spring Boot app is available over on GitHub.

Course – LSS (cat=Security/Spring Security)

I just announced the new Learn Spring Security course, including the full material focused on the new OAuth2 stack in Spring Security:

res – Security (video) (cat=Security/Spring Security)
Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.