Installing CASshib and configuring ASI to use it

1. Install the following packages (in Ubuntu)

• apache2-mpm-worker (or -prefork or -event)
• libapache2-mod-gnutls
• libapache2-mod-shib2
• tomcat6

1. Edit /etc/tomcat6/server.xml

   • comment out all <Connector> elements

   • add a Connector element:

     <Connector port="8765" protocol="AJP/1.3"
                enableLookups="false"
                tomcatAuthentication="false"
                address="127.0.0.1" />

   • optionally add another Connector for debugging purposes:

     <Connector port="8585" protocol="HTTP/1.1"
                connectionTimeout="20000"
                address="127.0.0.1" />

   • double-check that there are no uncommented Connector elements without address="127.0.0.1"

   • see the following link for more information: http://code.google.com/p/casshib/wiki/ShibbolethApacheTomcatInstallationAndConfigurationForCASShib#Tomcat_Configuration

2. Configure Apache to use Shibboleth and act as a reverse proxy forwarding requests to Tomcat. These instructions are for Ubuntu, which uses a heavily customized layout for Apache configuration files.

   • disable all sites (sudo a2dissite <site-name>) and enable the site default-ssl (sudo a2ensite default-ssl)

   • enable required modules: sudo a2enmod gnutls proxy proxy_ajp shib2

   • edit /etc/apache2/ports.conf and comment out the following lines:

     NameVirtualHost *:80
     Listen 80

   • replace the contents of the file /etc/apache2/sites-enabled/default-ssl with the following:

     <VirtualHost _default_:443>
         ServerName https://your.hostname:443
     
         GnuTLSEnable on
         GnuTLSPriorities NORMAL
     
         # Use a self-signed (snakeoil) certificate
         GnuTLSCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
         GnuTLSKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
     
         # Serve these files directly
         ProxyPass /shibboleth-sp !
         Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css
         Alias /shibboleth-sp/logo.jpg /usr/share/shibboleth/logo.jpg
     
         ProxyRequests Off
         <Proxy *>
             Order deny,allow
             Allow from all
         </Proxy>
     
         # always keep the host header
         ProxyPreserveHost On
     
         ProxyPass / ajp://localhost:8765/
     
         UseCanonicalName On
     
         # Protect the login and Shibboleth.sso URLs.
         <LocationMatch "/casshib/shib/[^/]*/(login|Shibboleth.sso(/[^/]*)?)">
             AuthType shibboleth
             ShibRequireSession On
             ShibUseHeaders On
             require valid-user
         </LocationMatch>
     
     </VirtualHost>

3. Restart Tomcat and Apache

4. Edit the file /etc/shibboleth/shibboleth2.xml

   • if <RequestMapper type="Native"> exists, delete or comment out it and its contents

   • add the following under the root element (<SPConfig>):

         <RequestMapper type="Native">
             <RequestMap applicationId="default">
                 <!-- the attribute 'name' must match the hostname in Apache's ServerName directive: -->
                 <Host name="your.hostname" port="443" scheme="https">
                     <!-- add a PathRegex element for each service: -->
                     <PathRegex regex="casshib/shib/app1" applicationId="app1" authType="shibboleth" requireSession="true"/>
                     ...
                 </Host>
             </RequestMap>
         </RequestMapper>

   • edit the element <ApplicationDefaults>:

         <ApplicationDefaults id="default" policyId="default"
                              entityID="https://your.hostname/BOGUS_SERVICE"
                              homeURL="https://your.hostname/BOGUS_SERVICE"
                              REMOTE_USER="shibattr-eppn"
                              signing="false" encryption="false">

     Under the element, add ApplicationOverride for each service:

         <ApplicationDefaults id="default" ...>
             ...existing elements...
     
             <ApplicationOverride id="app1"
                                  entityID="https://your.hostname/casshib/app1"
                                  homeURL="https://app1.url/"
                                  REMOTE_USER="shibattr-eppn">
                 <!-- NOTE the cookieProps path is different for each service.
                      The handlerURL needs to fall within the path of the cookie. -->
                 <Sessions lifetime="28800" timeout="3600" checkAddress="false"
                           handlerURL="/casshib/shib/app1/Shibboleth.sso" handlerSSL="true"
                           exportLocation="/casshib/shib/app1/Shibboleth.sso/GetAssertion" 
                           idpHistory="false" idpHistoryDays="7"
                           cookieProps="; path=/casshib/shib/app1">
                 </Sessions>
             </ApplicationOverride>
             ...
         </ApplicationDefaults>

5. Run the following commands:

   sudo sed -i -e 's/\bid="/id="shibattr-/' /etc/shibboleth/attribute-map.xml
   sudo sed -i -e 's/\b\(attributeID="\)\([^\*]\)/\1shibattr-\2/' /etc/shibboleth/attribute-policy.xml

6. Restart shibd

7. Download CASshib

8. Extract the package and copy the file casshib-server-x.x.xx/modules/casshib-server-webapp-x.x.xx.war to /var/lib/tomcat6/webapps/casshib.war (as root). Tomcat should automatically extract the package to the subdirectory casshib.

9. Edit the file /var/lib/tomcat6/webapps/casshib/WEB-INF/classes/casshib-service-registrations.xml:

   • add a <service> element under <casShibServiceRegistrations>:

     <service id="https://idp03.aalto.fi/idp/shibboleth"
              appname="name"
              passcode="96306" />

     TODO: explain where the id attribute comes from

TODO: callback and ASI configuration