CAS SSO With Spring Security

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.

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 https://github.com/apereo/cas-overlay-template.git 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 application.properties in the folder, too:

server.port=8443
spring.main.allow-bean-definition-overriding=true
server.ssl.key-store=classpath:/etc/cas/thekeystore
server.ssl.key-store-password=changeit

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

./gradlew[.bat] run -Dorg.gradle.java.home=$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 cas.properties. Now, we can define a static user in the properties file:

cas.authn.accept.users=casuser::Mellon

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')) {
            casRunArgs.addAll(project.args.split('\\s+'))
        }
        javaexec {
            main = "-jar"
            jvmArgs = casRunArgs
            args = ["build/libs/${casWebApplicationBinaryName}"]
            logger.info "Started ${commandLine}"
        }
    }
}

We then save the file and run:

./gradlew run
  -Dorg.gradle.java.home=$JAVA11_HOME
  -Pargs="-Dcas.standalone.configurationDirectory=/cas-server/src/main/resources/etc/cas/config"

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:

<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-cas</artifactId>
    <versionId>5.3.0.RELEASE</versionId>
</dependency>

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

server.port=8900
spring.freemarker.suffix=.ftl

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" : "org.apereo.cas.services.RegexRegisteredService",
  "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.

cas.serviceRegistry.initFromJson=true
cas.serviceRegistry.json.location=classpath:/etc/cas/services

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:

@Bean
public CasAuthenticationFilter casAuthenticationFilter(
  AuthenticationManager authenticationManager,
  ServiceProperties serviceProperties) throws Exception {
    CasAuthenticationFilter filter = new CasAuthenticationFilter();
    filter.setAuthenticationManager(authenticationManager);
    filter.setServiceProperties(serviceProperties);
    return filter;
}

@Bean
public ServiceProperties serviceProperties() {
    logger.info("service properties");
    ServiceProperties serviceProperties = new ServiceProperties();
    serviceProperties.setService("http://cas-client:8900/login/cas");
    serviceProperties.setSendRenew(false);
    return serviceProperties;
}

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

@Bean
public CasAuthenticationProvider casAuthenticationProvider(
  TicketValidator ticketValidator,
  ServiceProperties serviceProperties) {
    CasAuthenticationProvider provider = new CasAuthenticationProvider();
    provider.setServiceProperties(serviceProperties);
    provider.setTicketValidator(ticketValidator);
    provider.setUserDetailsService(
      s -> new User("[email protected]", "Mellon", true, true, true, true,
      AuthorityUtils.createAuthorityList("ROLE_ADMIN")));
    provider.setKey("CAS_PROVIDER_LOCALHOST_8900");
    return provider;
}

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:

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests().antMatchers( "/secured", "/login").authenticated()
      .and()
      .exceptionHandling().authenticationEntryPoint(authenticationEntryPoint())
      .and()
      .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.

@GetMapping("/logout")
public String logout(
  HttpServletRequest request, 
  HttpServletResponse response, 
  SecurityContextLogoutHandler logoutHandler) {
    Authentication auth = SecurityContextHolder
      .getContext().getAuthentication();
    logoutHandler.logout(request, response, auth );
    new CookieClearingLogoutHandler(
      AbstractRememberMeServices.SPRING_SECURITY_REMEMBER_ME_COOKIE_KEY)
      .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:

@Bean
public SecurityContextLogoutHandler securityContextLogoutHandler() {
    return new SecurityContextLogoutHandler();
}

@Bean
public LogoutFilter logoutFilter() {
    LogoutFilter logoutFilter = new LogoutFilter("https://localhost:8443/logout",
      securityContextLogoutHandler());
    logoutFilter.setFilterProcessesUrl("/logout/cas");
    return logoutFilter;
}

@Bean
public SingleSignOutFilter singleSignOutFilter() {
    SingleSignOutFilter singleSignOutFilter = new SingleSignOutFilter();
    singleSignOutFilter.setCasServerUrlPrefix("https://localhost:8443");
    singleSignOutFilter.setLogoutCallbackPath("/exit/cas");
    singleSignOutFilter.setIgnoreInitConfiguration(true);
    return singleSignOutFilter;
}

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:

cas:
    authn:
        accept:
            users:
        jdbc:
            query[0]:
                sql: SELECT * FROM users WHERE email = ?
                url: jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
                dialect: org.hibernate.dialect.MySQLDialect
                user: root
                password: root
                ddlAuto: none
                driverClass: com.mysql.cj.jdbc.Driver
                fieldPassword: password
                passwordEncoder:
                    type: NONE

spring.jpa.generate-ddl=false
spring.datasource.url= jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

@Bean
public CasUserDetailsService getUser(){
    return new CasUserDetailsService();
}

@Bean
public CasAuthenticationProvider casAuthenticationProvider(
  TicketValidator ticketValidator,
  ServiceProperties serviceProperties) {
    CasAuthenticationProvider provider = new CasAuthenticationProvider();
    provider.setServiceProperties(serviceProperties);
    provider.setTicketValidator(ticketValidator);
    provider.setUserDetailsService(getUser());
    provider.setKey("CAS_PROVIDER_LOCALHOST_8900");
    return provider;
}

public class CasUserDetailsService implements UserDetailsService {

    @Autowired
    private UserRepository userRepository;

    @Override
    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(
            casUser.getEmail(),
            casUser.getPassword(),
           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.