CAMS 2.x IdP run book

This page is under construction

Executive Summary

Install and configure Apache httpd

Install needed RPMs

Use stock httpd RPM install (standard NIST install)
Install mod_ssl and mod_auth_kerb RPMs:
```
# yum install mod_ssl
```

Configure

Current versions of the various httpd configuration files can be obtained in the touchstone locker, in /mit/touchstone/config/idp2-cams/httpd/.

Install the server certificate, key, and CA files in /etc/pki/tls/certs/ and /etc/pki/tls/private/, as appropriate, and make sure the paths are correct in ssl.conf and idp-attr-query.conf (see below). The key file should be readable by only the tomcat user, as the idp webapp also uses it.
In /etc/httpd/conf/httpd.conf, set ServerName:
```
ServerName idp.touchstonenetwork.net:80
```
and set the UseCanonicalName option to On:
```
UseCanonicalName On
```
Disable the stock "Welcome" page, by commenting out the lines in /etc/httpd/conf.d/welcome.conf

In /etc/httpd/conf.d/ssl.conf, set the SSLRandomSeed options:

SSLRandomSeed startup file:/dev/urandom 1024
SSLRandomSeed connect file:/dev/urandom 1024

within the VirtualHost block, set the ServerName:

ServerName idp.touchstonenetwork.net:443

set the SSL cipher suite:

SSLCipherSuite HIGH:MEDIUM:EXP:!aNULL:!SSLv2:+SHA1:+MD5:+HIGH:+MEDIUM:+EXP

Install the server certificate, key, and CA files in /etc/pki/tls/certs/ and /etc/pki/tls/private/, as appropriate, and set the paths in ssl.conf:

SSLCertificateFile /etc/pki/tls/certs/idp.touchstonenetwork.net-cert.pem
SSLCertificateKeyFile /etc/pki/tls/private/idp.touchstonenetwork.net-key.pem
SSLCertificateChainFile /etc/pki/tls/certs/EquifaxCA.pem
SSLCACertificateFile /etc/pki/tls/certs/mitCAclient.pem

set the SSL options:

SSLOptions +StrictRequire

configure custom logging:

CustomLog logs/ssl_request_log \
    "%t %h %{HTTPS}x %{SSL_PROTOCOL}x %{SSL_CIPHER}x %{SSL_CIPHER_USEKEYSIZE}x %{SSL_CLIENT_VERIFY}x \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""

ensure that all access is via SSL:

<Directory />
    SSLRequireSSL
</Directory>

ensure that all rewrite rules are inherited:

RewriteEngine On
RewriteOptions inherit

Install these additional conf files from the touchstone locker (/mit/touchstone/config/idp2-cams/httpd) in /etc/httpd/conf.d:
- cams.conf
  This adds configuration to protect Cams application resources appropriately.
- idp-attr-query.conf
  This sets up the vhosts for back-channel attribute queries on port 8443.
- idp-rewrite.conf
  This adds various rewrite rules for compatibility, etc.
- proxy_ajp.conf
  Configures the AJP proxy module for the idp and cams webapps (replaces version installed by httpd).
- ssl.conf (see above)
- welcome.conf (see above)
Install our standard robots.txt and favicon.ico files in /var/www/html. The robots.txt should disallow all access:
```
User-agent: *
Disallow: /
```
Current versions of these files may be found in the touchstone locker, in /mit/touchstone/config/htdocs/.
Make sure httpd is started at boot time:
```
# chkconfig httpd on
```
Add the following settings to the stock /etc/logrotate.d/httpd configuration file:
```
daily
rotate 100
compress
delaycompress
```
This will cause the httpd log files in /var/log/httpd/ to be rotated daily and compressed, saving 100 days of old logs (in case we need them for quarterly metrics).

Install JDK and enhanced JCE

The IdP uses JDK 1.6; download and install the RPM from Sun, or use the version in the downloads directory in the touchstone locker (jdk-6uNN-linux-amd64.rpm, where NN is the update number):
```
# rpm -Uvh jdk-6uNN-linux-amd64.rpm
```

To support additional cryptographic algorithms used by the IdP, download and install the Bouncy Castle JCE jar file (http://polydistortion.net/bc/index.html) in the lib/ext directory of the JRE (/usr/java/latest/jre/lib/ext/). For example:
```
# cd /usr/java/latest/jre/lib/ext
# cp /path/to/bcprov-jdk16-145.jar .
```
(Replace the file version number as needed).
Add it as a provider in in the JRE's lib/security/java.security, e.g.:
```
security.provider.9=org.bouncycastle.jce.provider.BouncyCastleProvider
```
(Replace 9 with the next sequential provider number as needed).

To support use of crypto key sizes larger than 2048 bits, we also add the Unlimited Strength Security Policy to the JVM. Download jce_policy-6.zip from the locker downloads directory, or from Sun (http://java.sun.com/javase/downloads/index.jsp, Other Downloads section at the bottom). Unzip the policy zip file and copy local_policy.jar and US_export_policy.jar into the JRE's lib/security directory (replacing the versions installed from the JDK RPM).
```
# cd /tmp
# unzip /path/to/jce_policy-6.zip
# cd jce
# cp *.jar /usr/java/latest/jre/lib/security/
```

For convenience, install shell profile scripts in /etc/profile.d that define JAVA_HOME, e.g. java.csh:

setenv JAVA_HOME /usr/java/default
if ( "${path}" !~ *${JAVA_HOME}/bin* ) then
    set path = ( ${JAVA_HOME}/bin $path )
endif

java.sh:

export JAVA_HOME=/usr/java/default
if ! echo $PATH | grep -q ${JAVA_HOME}/bin ; then
    export PATH=${JAVA_HOME}/bin:$PATH
fi

Install Tomcat

Download current Tomcat 6.0 binary distribution (tested with 6.0.20, available in /mit/touchstone/downloads/apache-tomcat-6.0.20.tar.gz, and install under /usr/local:
```
# cd /usr/local
# tar xzf /path/to/apache-tomcat-6.0.20.tar.gz
# rm -f tomcat
# ln -s apache-tomcat-6.0.20.tar.gz tomcat
```

Create the tomcat user, and change the ownership of the tomcat tree:

# groupadd -g 52 tomcat
# useradd -u 52 -g tomcat -c "Tomcat User" -d /usr/local/tomcat -M -s /sbin/nologin tomcat
# chown -R tomcat:tomcat /usr/local/apache-tomcat-6.0.20

Install our version of conf/server.xml (from /mit/touchstone/config/idp2-core/tomcat), which properly configures the AJP connector on port 8009, and disables the HTTP connector on port 8080.

Install the tomcat init script (from /mit/touchstone/maint/init/tomcat) in /etc/init.d/, and make sure tomcat is started at boot time:
```
# chkconfig --add tomcat
```

Install Shibboleth IdP

Run the idp application installer from our customized binary distribution, available in /mit/touchstone/builds/NIST/idp2-cams/cams-shibboleth-identityprovider-2.x.y-bin.tgz, and the install script contained therein. For example:
```
# cd /tmp
# rm -rf shibboleth-identityprovider-2.*
# tar xzf /path/to/cams-shibboleth-identityprovider-2.1.5-bin.tgz
# cd shibboleth-identityprovider-2.1.5
# ./install.sh
[There should be no need to override the default responses to the installer's questions.]
```
By default (because of one of our customizations to the stock Internet2 distribution) this will install under /usr/local/shibboleth-idp/. The installer will not overwrite the configuration files of an existing installation. For a new installation, the installer will generate a keystore, and prompt for its password; currently we do not use this keystore, so the password does not matter. This distribution contains the standard shibboleth-identityprovider binary distribution, from the Internet2 zip file (http://shibboleth.internet2.edu/downloads/shibboleth/idp/latest/), plus the following customizations:
- camslogin
  This provides the custom login pages for CAMS users. It is available as a tarball (/mit/touchstone/builds/NIST/idp2-cams/camslogin.tgz) which is unpacked into the top-level directory of the binary distribution.
- CamsLoginModule (cams-jaas-loginmodule-x.y.jar)
  This is the JAAS login module for CAMS. It is available as a .jar file in /mit/touchstone/builds/NIST/cams-jaas-loginmodule-x.y.jar, where x.y is the version number (currently 1.0). It must be copied into the lib subdirectory of the binary distribution.
- camsutil-1.0.jar
  This is a helper package used by the login module to validate the username/password. It is available in /mit/touchstone/builds/NIST/camsutil-1.0.jar. It must be copied into the lib subdirectory of the binary distribution along with the login module jar file.
The installer will create and populate /usr/local/shibboleth-idp; the web application (war) file will be in /usr/local/shibboleth-idp/war/idp.war, but the current version of the idp.war will be available in the locker (/mit/touchstone/builds/NIST/idp2-mit/idp.war).
The idp application, running under Tomcat, needs full access to the install directory, so make sure it is owned by the tomcat user, e.g.:
```
# chown -R tomcat:tomcat /usr/local/shibboleth-idp
```
To ensure that we run the current version of the web application, download the latest idp.war file from the touchstone locker (/mit/touchstone/builds/NIST/idp2-mit/idp.war) and copy it into /usr/local/tomcat/webapps/:
```
# cp /path/to/idp.war /usr/local/tomcat/webapps/
# chown tomcat:tomcat /usr/local/tomcat/webapps/idp.war
```

Copy the idp's endorsed jar files to tomcat's endorsed dir:

# mkdir -p /usr/local/tomcat/endorsed
# cp -p /usr/local/shibboleth-idp/lib/endorsed/*.jar /usr/local/tomcat/endorsed/
# chown -R tomcat:tomcat /usr/local/tomcat/endorsed

Copy in the idp config files for the server, to the conf subdirectory; these include:
- attribute-filter.xml
- attribute-resolver.xml
- handler.xml
- internal.xml
- logging.xml
- login.config
- relying-party.xml
- service.xml
- tc-config.xml (for terracotta clustering)

Terracotta

(See https://spaces.internet2.edu/display/SHIB2/IdPCluster)

The terracotta software is used to cluster the IdP nodes. Each node must run the terracotta server, as well as the instrumented client (tomcat, in our case). The terracotta server operates in either the active or passive role; only one server should be in the "active/coordinator" state at a time.

Download the terracotta tarball; our current version is in the touchstone locker, in /mit/touchstone/downloads/terracotta-x.y.z.tar.gz. Extract it under /usr/local, create a logs directory for it, make it owned by the tomcat user, and symlink /usr/local/terracotta to it. For example (replace 3.1.1 with the appropriate terracotta version number):

# cd /usr/local
# tar xzf /path/to/terracotta-3.1.1.tar.gz
# mkdir -p terracotta-3.1.1/logs
# chown -R tomcat:tomcat terracotta-3.1.1
# rm -f terracotta
# ln -s terracotta-3.1.1 terracotta

The IdP requires the installation of a couple of Terracotta Integration Modules, and the generation of a boot jar file for Tomcat, which is specific to the Java version:

# setenv TC_HOME /usr/local/terracotta-3.1.1
# setenv TC_INSTALL_DIR $TC_HOME
# setenv JAVA_HOME /usr/java/default
# $TC_HOME/bin/tim-get.sh install tim-vector 2.5.1 org.terracotta.modules
# $TC_HOME/bin/tim-get.sh install tim-tomcat-6.0 2.0.1
# $TC_HOME/bin/make-boot-jar.sh -f /usr/local/shibboleth-idp/conf/tc-config.xml

Be sure to regenerate this jar after installing a new JDK.

Install the init script from /mit/touchstone/maint/shibboleth-idp/terracotta/terracotta.init in /etc/init.d, and make sure it is configured to start at boot time. Note that terracotta must be started before tomcat.

# cp /path/to/terracotta.init /etc/init.d/terracotta
# chmod 755 /etc/init.d/terracotta
# chkconfig --add terracotta

To avoid performance impact during business hours, we disable automatic garbage collection of terracotta objects. Instead, we run a nightly cron job to do the garbage collection manually. Since this should only be done on the active/coordinator node, the script, run-dgc-if-active.sh, checks the server mode, then runs the garbage collector if and only if the server is the active node. Both the script and cron file can be obtained in /mit/touchstone/maint/shibboleth-idp/terracotta/; install as follows:

# cp /path/to/run-dgc-if-active.sh /usr/local/shibboleth-idp/bin/
# cp /path/to/run-dgc.cron /etc/cron.d/run-dgc

Shibboleth SP

The CAMS application needs to authenticate against our IdPs, and so requires the Shibboleth service provider (SP) software to run, as well as the IdP software.

Installation

We use the stock RHEL 5 64-bit RPMs, available from the Internet2 downloads site; the current RPMs are available in the touchstone locker downloads directory. Install the following RPMs:

log4shib
opensaml
shibboleth
xerces-c
xml-security-c
xmltooling

Configuration

The SP configuration files live in /etc/shibboleth:

shibboleth2.xml (main SP configuration file)
attribute-map.xml (defines our attribute mappings)
native.logger (configures Apache module logging – we modify the stock configuration to log under /var/log/shibboleth instead of /var/log/httpd, because the apache user must have write access to the directory)

Note that SELinux must be set to permissive mode in order for the SP to function properly; otherwise (without modifying policy) its Apache module will be unable to connect to the shibd socket (which lives in /var/run/shibboleth/). Edit /etc/selinux/config accordingly.

Child pages