Overview

CAS Toolbox is a tool meant :

deploying a CAS server into an existing Tomcat installation
simplifying CAS configuration
customizing the CAS server
building quickstart distributions

This package is develop by Esup-portail Consortium

Download

The CAS Toolbox package is available at https://sourcesup.cru.fr/frs/?group_id=401
Subversion : https://subversion.cru.fr/cas-toolbox

File organization

cas-toolbox-X-Y
   | custom
   | resources
   |    | [...]
   | update
   |    | source
   |    |    | [...]
   |    | webpages
   |    |    | [...]
   | update.esup
   | build.sample.properties
   | build.xml
   | config.sample.properties
   | README

custom: customization folder
resources: resources folder, including package dependencies

update: update folder, containing add-ons to the original JASIG CAS Server
build.sample.properties: sample deployment config file

build.xml: ANT build file

config.sample.properties: simple CAS config file

README
Usage

Expand cas-toolbox.X-Y.tar.gz
Rename build.sample.properties to build.properties
Set the deploy.path property in build.properties
Rename config.sample.properties to config.properties
Configure config.properties
Initialize by running ant init
Deploy by running ant deploy
Start Tomcat and browse http://localhost:8080/cas
Configuration

CAS Toolbox is designed to handle different configuration and/or customization levels.

4 different levels

The 'update' folder contains the first level of add-ons to the original JASIG CAS Server distribution.
The 'custom' folder allows to customize every aspect of the CAS Server installation (look and feel, Java sources, configuration files).
The 'config.properties' files allows to set properties will be used by the CAS Server Spring configuration files.
CAS Toolbox can handle as many different 'update' folders as you need, one only is required.

In the build.properties file, you can specify a Subversion repository should present an update-XXX folder, used during the initialization step.

svnant.update.url=http://subversion.cru.fr/cas-toolbox/trunk/update.esup/
svnant.repository.user=
svnant.repository.passwd=
svnant.update.path=${basedir}/update.esup
svnant.update.version=HEAD

You can chain several update folders in the build.properties file:

update.path=${basedir}/update,${basedir}/update.esup

The order is meaningful: the last update folder always overwrites files from previous updates.

Updates and custom folders

These folders may contain :

a source folder : java classes that will be compiled and deployed with the original sources
a webpages folder: other files relative to the Tomcat webapp context in Tomcat (eg : WEB-INF/properties/my.properties)
Configuration

build.properties

deploy.path=/home/cas/webapps/cas
config.file=${basedir}/config.properties

deploy.path: the path where files will be deployed.
config.file: the main configuration file.

maven.offline=false

Set this property to false the first time you use the init task, allowing Maven to download dependencies. Set it to true with no Internet access.

update.path=${basedir}/update
custom.path=${basedir}/custom

You can this way customize the update and cutom folders if you don't want to use the default ones.

config.properties

The config.properties allows to specify your own authentication handlers:

cas.authHandlers=ldapHandler,fileHandler

Available handlers are listed in the build.properties file : ldapHandler, fileHandler, jdbcHandler, radiusHandler, etc ...
During the initialization step, this property is used to :

deploy libraries needed by the handlers used
deploy specific configuration files xxx-auth.xml (available template files are file-auth.xml, ldap-auth.xml and simpletest-auth.xml).

Specific properties should set in to config.properties (these properties will be used by the specific configuration files of the handlers):
Example for the LDAP handler:

#
# config.properties
#
ldap.host.1=ldap://ldap1.univ-nancy2.fr:392
ldap.host.2=ldap://ldap2.univ-nancy2.fr:392
ldap.basedn=uid=%u,ou=people,dc=univ-nancy2,dc=fr

ldap-auth.xml :

<bean id="ldapHandler" class="org.jasig.cas.adaptors.ldap.FastBindLdapAuthenticationHandler" lazy-init="true">
  <property name="filter" value="${ldap.basedn}" />
  <property name="contextSource">
    <bean class="org.jasig.cas.adaptors.ldap.util.AuthenticatedLdapContextSource">
      <property name="pooled" value="true"/>
      <property name="anonymousReadOnly" value="true" />
      <property name="urls">
        <list>
          <value>${ldap.host.1}</value>
          <value>${ldap.host.2}</value>
        </list>
      </property>
    </bean>
  </property>
</bean>

Apart from these specific properties, the file config.properties also contains global properties used by the CAs server itself:

#logs directory
log.dir=${catalina.home}/logs

#cas host
cas.host=jmarchal-dev.univ-nancy2.fr
# cas uri (empty if /)
cas.uri=
# cas port empty (if standard)
cas.port=

#User allow to use services manager (services/manage.html)
security.useradmin=admin

# graphic theme
theme=default
views=default

Handler customization

Below is an customization example for the LDAP authentication handler (we want here to add LDAP connection timeouts).

Copy update/webpages/WEB-INF/ldap-auth.xml to custom/webpages/WEB-INF/ldap-auth.xml

Edit custom/webpages/WEB-INF/ldap-auth.xml:

<bean id="ldapHandler" class="org.jasig.cas.adaptors.ldap.FastBindLdapAuthenticationHandler" lazy-init="true">
  <property name="filter" value="${ldap.basedn}" />
  <property name="contextSource">
    <bean class="org.jasig.cas.adaptors.ldap.util.AuthenticatedLdapContextSource">
      <property name="pooled" value="true"/>
      <property name="anonymousReadOnly" value="true" />
      <property name="urls">
        <list>
          <value>${ldap.host.1}</value>
          <value>${ldap.host.2}</value>
        </list>
      </property>

      <property name="baseEnvironmentProperties">
        <map>
	  <entry key="com.sun.jndi.ldap.connect.timeout" value="${ldap.connect.timeout}"/>
          <entry key="com.sun.jndi.ldap.read.timeout" value="${ldap.read.timeout}"/>
        </map>
      </property>
    </bean>
  </property>
</bean>

Edit config.properties to set ldap.connect.timeout and ldap.read.timeout properties :
```
# Ldap timeout
ldap.connect.timeout=100
ldap.read.timeout=30
```
Run ant init
Run ant deploy.
Build a quickstart distribution

Once your installation has been customized, CAS Toolbox offers an easy way of building quickstart distributions:

Edit build.properties and add the following properties (see resources/quickstart/quickstart.properties):

tomcat.download.url=http://apache.miroir-francais.fr/tomcat/tomcat-6/v6.0.14/bin/apache-tomcat-6.0.14.tar.gz
tomcat.version=apache-tomcat-6.0.14
tomcat.port.stop=8005
tomcat.port.http=8080
tomcat.port.redirect=8443
tomcat.port.ajp=8009

Run ant _make.quickstart
Tomcat will be automatically downloaded and embedded into in the package

The resulting quickstart package is available as build/quickstart/cas-quickstart-X.Y.Z-A.tar.gz
The Esup Update

Esup gives provides an update folder more accurate for French universities.
esup-upadte folder is now include in cas-toolbox.

Other update.XXXX use

Check the following properties in build.properties:

svnant.update.url=http://subversion.cru.fr/cas-toolbox/tags/[CAS-TOOLBOX_VERSION]/update.XXXX/
svnant.repository.user=
svnant.repository.passwd=
svnant.update.path=${basedir}/update.XXXX
svnant.update.version=HEAD

Refer to this folder in the update.path property :

update.path=${basedir}/update,${basedir}/update.XXXX

Run ant _get.remoteUpdate
Folder update.XXXX will be downloaded from subversion

Others updates

update.stats
update.memcache
update.blockattack

Quickstart usage

unzip cas-quickstart-X.Y.Z-Q.tar.gz
cd cas-quickstart-X.Y.Z-Q
modify env.cmd (or env.sh)

- JAVA_HOME
launch start.cmd (start.sh)

Central Authentication Service

CAS-toolbox