Saturday, August 22, 2015

Setup CAS server tutorial

Prerequisites 

For setting up the CAS server the following must be installed:
I assume that you have knowledge of all these technologies and I will not go into many details about them.

Setup CAS server project

CAS uses Maven to build a deployable package which can be installed into a Java servlet container. In this tutorial we'll use Tomcat as a container.

Also CAS server makes use of Maven overlay which makes the setup very easy and provides default configurations and flows which can be easily updated to your needs.

To make things faster I will provide below the pom.xml which contains only the dependency to the cas server webapp and the configured maven overlay build plugin. Importing the pom.xml as a maven project into an IDEs such as Intellij will generate an overlays folder which contains the defaults of CAS server, browsing through them will help you understand how it works. 

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.blogspot.robertrusu.cas</groupId>
  <artifactId>cas-server</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>war</packaging>

  <name>cas-server</name>
  <url>http://maven.apache.org</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 <cas.version>4.0.2</cas.version>
  </properties>

  <dependencies>
        <dependency>
            <groupId>org.jasig.cas</groupId>
            <artifactId>cas-server-webapp</artifactId>
            <version>${cas.version}</version>
            <type>war</type>
            <scope>runtime</scope>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.6</version>
                <configuration>
                    <warName>cas</warName>
                    <overlays>
                        <overlay>
                            <groupId>org.jasig.cas</groupId>
                            <artifactId>cas-server-webapp</artifactId>
                            <excludes>
                                <exclude>WEB-INF/cas.properties</exclude>
                                <exclude>WEB-INF/classes/log4j.xml</exclude>
                            </excludes>
                        </overlay>
                    </overlays>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.2</version>
            </plugin>
        </plugins>
        <finalName>cas</finalName>
    </build>
 
</project>


Configuration of CAS server


You will need to copy into yourTomcatInstallationPath/conf/cas folder two configuration files, to be easier for you can take them from github and later change them to fit your needs.
  • cas.properties contains CAS configuration which can be changed at runtime without the need to build the web application again. Of course after changing the configuration you will need to reload the application or restart tomcat.
  • log4j.xml contains the logging configuration for CAS server
It is very important to change in cas.properties the configuration which points to the location of log4j.xml otherwise the server will not be deployed successfully.

log4j.config.location=yourTomcatInstallationPath/cas/cas/log4j.xml

You will need to create in your project a spring configuration xml file which will replace the one from the cas-webapp dependency at build time. The file name must be propertyFileConfigurer.xml and its location must be inside your project at:
src/main/webapp/WEB-INF/spring-configuration/propertyFileConfigurer.xml
The file contains the location of the CAS server configuration which will be picked at runtime, when deploying the webapp in Tomcat. The content is the following (just replace yourTomcatInstallationPath):

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

       xmlns:context="http://www.springframework.org/schema/context"

       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd

       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <context:property-placeholder location="file:yourTomcatInstallationPath/conf/cas/cas.properties"/>

</beans>



Build it and run it

  • Build the webapp using: mvn clean install
  • Copy the obtained cas.war file into yourTomcatInstallationPath/webapps
  • Start tomcat (startup.bat)
  • Visit http://localhost:8080/cas
You will see the default look of the CAS server together with a login form. To test it you can use the dummy username "casuser" and its password "Mellon".  
These are configured in next xml file overlays/org.jasig.cas.cas-server-webapp-4.0.2/WEB-INF/deployerConfigContext.xml in the primaryAuthenticationHandler bean. 

If you are not able to access the CAS server web application after you deployed the war file into tomcat checking the container logs or the CAS logs will probably help you to fix the issue. 


The end!

As you've seen I did not get into to much details and kept it short. I will try to make some posts on how to further configure the server to use some various authentication handlers or how to register cas clients. If you have any suggestions please leave a comment below. 

To better understand CAS I suggest that you also read the following article CAS - Central Authentication Service which contains an introduction into CAS and also a lot of useful resources to get you started. 

 Robert Rusu

Update: Even if at the time when I wrote this tutorial the CAS Server had version 4.0.2, the same steps can be applied, maybe small adjustments might be needed like using the latest configuration samples.