The purpose of this document is to guide you through the installation process of the Apereo CAS 5.1.X. This SSO is used by Gazelle tools to authenticate users.
Installation needs to be performed on a Debian linux Stretch or newer. This is know to not work on jessie. Apereo needs to be embedded into a Tomcat 8 server. Tomcat 8 runs under Java 8. Make sure you have zulu-8 installed.
apt-get install tomcat8
Note: the next steps assume that tomcat8 installation folder is at /var/lib/tomcat8
You can force tomcat8 to use zulu-8 by adding JAVA_HOME=/usr/lib/jvm/zulu-8-amd64 in /etc/init.d/tomcat8.
The following line is necessary in order to securise the tomcat server
sudo rm -r /var/lib/tomcat8/webapps/ROOT
Identify the offset to use for the apache tomcat8 server. If you already have some services listening on 8080 you need to change the default port in the configuration file of tomcat. Make sure to enable AJP while you are editing the port numbers.
sudo vi /var/lib/tomcat8/conf/server.xml
In the example below, we shift the listening port to 8580.
<Server port="8505" shutdown="SHUTDOWN">
...
<Connector port="8580" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
Probably you want to use AJP connector. You need to uncomment this line and customize the port
<Connector port="8509" protocol="AJP/1.3" redirectPort="8443" />
Also add secretRequired="false" in the AJP configuration.
cd /var/lib/tomcat8/webapps
sudo wget https://gazelle.ihe.net/apereo-cas-gazelle/cas.war
The following step is necessary if you want to have the application to respond at the URL https://XXXXX/sso
mv cas.war sso.war
It is easy to customize the portal with the logo of the installation.
cd /var/lib/tomcat8/webapps/sso/WEB-INF/classes/static/themes/gazelle/images
wget URL_TO_LOGO
convert LOGO logo.png
cp logo.png cas-logo.png
chown tomcat8:tomcat8 cas-logo.png
Edit css file to adjust the size of the images. You may want to use your browser inspector in order to find the right values. Once you have them add them to the following file.
cd /var/lib/tomcat8/webapps/sso/WEB-INF/classes/static/themes/gazelle/css
vi cas.css
On the home page it is possible to add some links for lost password and create account.
Edit the file /var/lib/tomcat8/webapps/sso/WEB-INF/classes/messages.properties to add the two lines below
screen.pm.button.forgotpwd=<a href="https://stretch.localdomain/gazelle/users/login/passwordAssist.seam">Forgot your password? </a>
screen.pm.button.createAccount=<a href="https://stretch.localdomain/gazelle/users/user/register.seam">Create an account </a>
Then in the file loginform.html add the following text on line 95
vi /var/lib/tomcat8/webapps/sso/WEB-INF/classes/templates/fragments/loginform.html
<div th:unless="${passwordManagementEnabled}">
<span class="fa fa-question-circle"></span>
<span th:utext="#{screen.pm.button.createAccount}" />
<p/>
</div>
<div th:unless="${passwordManagementEnabled}">
<span class="fa fa-question-circle"></span>
<span th:utext="#{screen.pm.button.forgotpwd}" />
<p/>
</div>
The apereo configuration files are located in the folder /etc/cas. Sample configuration architecture is provided in the archive file located here [https://gazelle.ihe.net/apereo-cas-gazelle/cas.tgz]https://gazelle.ihe.net/apereo-cas-gazelle/cas.tgz
sudo su
cd /etc
wget https://gazelle.ihe.net/apereo-cas-gazelle/cas.tgz
tar zxvf cas.tgz
mkdir /etc/cas/log
chown -R tomcat8:tomcat8 cas
You then need to edit the file /etc/cas/config/cas.properties and match your system configuration
vi /etc/cas/config/cas.properties
In this file you need to replace all occurence of the string stretch.localdomain with the FQDN of your machine. You need also to make sure the database configuration matches your database setting.
In particular, two lines references the database. We usually bind the CAS to the database of Gazelle Test Management, so you might want to replace cas by gazelle. Your users database may be hosted in another server, in that case, make sure you will be able to access it from outside.
cas.authn.attributeRepository.jdbc[0].url=jdbc:postgresql://localhost:5432/cas
cas.authn.jdbc.query[0].url=jdbc:postgresql://localhost:5432/cas
Check also the path of the log files. Per default log files are set to be stored in the folder /var/log/cas. Make sure that the directory exists and is owned by the correct user
sudo mkdir /var/log/cas
sudo chown tomcat8:tomcat8 /var/log/cas
To rotate logs, in /etc/cas/config/log4j2.xml, add the following code in the first <RollingFile>, below </Policies>:
<DefaultRolloverStrategy max="5">
<Delete basePath="${sys:cas.log.dir}">
<IfFileName glob="*.log" />
<IfLastModified age="7d" />
</Delete>
</DefaultRolloverStrategy>
Restart tomcat.
Gazelle tools read the configuration of the SSO in a file located in /opt/gazelle/cas. We need to create this folder and the configuration file file.properties.
mkdir /opt/gazelle/cas
touch /opt/gazelle/cas/file.properties
chown -R jboss:jboss-admin /opt/gazelle/cas
chmod -R g+w /opt/gazelle/cas
Here is a sample of the content of the property file. Please replace stretch.localdomain with the FQDN of your server.
serverName=https://stretch.localdomain
casServerUrlPrefix=https://stretch.localdomain/sso
casServerLoginUrl=https://stretch.localdomain/sso/login
casLogoutUrl=https://stretch.localdomain/sso/logout
You almost there, restart tomcat8.
cf : https://apereo.github.io/cas/5.1.x/installation/Installing-ServicesMgmt-Webapp.html
The apache2 server needs to be aware of the proxy_pass to the tomcat8 server. So if you have configured tomcat to listen on ports with an offset of 200 you will have to add something like this :
<Location /sso>
ProxyPass ajp://localhost:8209/sso
ProxyPassReverse ajp://localhost:8209/sso
</Location>
Check that apache2 configuration is still ok
sudo apache2ctl configtest
If everything is ok you can then restart apache2
sudo apache2ctl restart
You should now access the Gazelle SSO login page at https://stretch.localname/sso.
Add the following line in setenv.sh. Create the file if it does not exist in {CATALINA_HOME}/bin or {CATALINA_HOME}/bin : it is usually in /usr/share/tomcat8/bin if tomcat was installed via apt.
CATALINA_OPTS="$CATALINA_OPTS -Dlog4j2.formatMsgNoLookups=true"
Replace the sso.war by the patch version available at https://gazelle.ihe.net/apereo-cas-gazelle/cas.war
cf : https://github.com/apereo/mod_auth_cas/blob/master/README
Edit or create file /etc/apache2/sites-available/gazelle-site-le-ssl.conf :
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerAdmin webmaster@localhost
ServerName FQDN
Header always set Strict-Transport-Security "max-age=63072000; includeSubdomains;"
DocumentRoot /var/www
CASCookiePath /var/cache/apache2/mod_auth_cas/
CASLoginURL https://FQDN/sso/login
CASValidateURL https://FQDN/sso/serviceValidate
<Location /index.html>
Authtype CAS
require valid-user
</Location>
...
</VirtualHost>
</IfModule>
FQDN is like gazelle.ihe.net
Activate some mods :
sudo a2enmod mod_ssl
sudo a2enmod mod_auth_cas