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

  Be Careful Actually base on 3.1.2 (work on 3.2)

Download

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

File organization

cas-toolbox-X-Y
   | custom
   | resources
   |    | [...]
   | update
   |    | source
   |    |    | [...]
   |    | webpages
   |    |    | [...]
   | 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

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

   Configuration

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

4 different levels

1. The 'update' folder contains the first level of add-ons to the original JASIG CAS Server distribution.
2. The 'custom' folder allows to customize every aspect of the CAS Server installation (look and feel, Java sources, configuration files).
3. The 'config.properties' files allows to set properties will be used by the CAS Server Spring configuration files.
4. 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 true the first time you use the init task, allowing Maven to download dependencies. Set it to false 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.
in order to use it :

• Check the following properties in build.properties:

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

• Refer to this folder in the update.path property :

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

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

  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)