Security Top

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

>> CHECK OUT THE 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 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

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

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 cas.properties:
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;
}

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:

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests().antMatchers( "/secured", "/login") 
      .authenticated() 
      .and().exceptionHandling() 
      .authenticationEntryPoint(authenticationEntryPoint());
}

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:

@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;
}

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/etc/cas/config/cas.properties:

cas.authn.accept.users=

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

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 principal 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:

@Bean
public CasAuthenticationProvider casAuthenticationProvider() {
    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;
}

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.

Security bottom

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

>> CHECK OUT THE COURSE
4 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Rado
Rado
2 years ago

Cas server not working for me, after filling user/password, there is a following error in log:

2017-12-02 21:58:25,432 ERROR [com.zaxxer.hikari.pool.HikariPool] –
com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

The last packet sent successfully to the server was 0 milliseconds ago. The driver has not received any packets from the server.

Me
Me
2 years ago
Reply to  Rado

Hey Rado – based on the exception you’re getting, you simply don’t have the database running (or accessible). You need to make sure that’s running and properly set up when you run the project.
Cheers,
Eugen.

Andrew
Andrew
2 years ago

I have problem with this example, after successful login every request redirect me to default localhost:9000 page instead of /secured

Loredana Crusoveanu
1 year ago
Reply to  Andrew

It’s probably redirecting you to the same page you were accessing before. If you want to always redirect to /secured, you have to add that in the security configuration.

Comments are closed on this article!