This page is under construction

Software

• Apache httpd 2.2 (from stock RHEL httpd RPM)
• mod_ssl (from stock RHEL mod_ssl RPM)
• mod_auth_kerb (from stock RHEL mod_auth_kerb RPM)
• Tomcat 6.0
• JDK 6.0 (from Sun, plus enhanced JCE and security policy)
• Shibboleth IdP 2.1
• terracotta 3.1

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 # yum install mod_auth_kerb

Configure

Current versions of the various httpd configuration files can be obtained in the touchstone locker, in /mit/touchstone/config/idp2-core/httpd/. The changes to the standard stock versions include:

• In /etc/httpd/conf/httpd.conf, set ServerName:

  ServerName idp.mit.edu: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.mit.edu: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.mit.edu-cert.pem SSLCertificateKeyFile /etc/pki/tls/private/idp.mit.edu-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\" %b"

  ensure that all access is via SSL:

  <Directory /> SSLRequireSSL </Directory>

  ensure that all rewrite rules are inherited:

  RewriteEngine On RewriteOptions inherit

• 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, cert-authn.conf, and idp-attr-query.conf.
• Install an HTTP keytab in /etc/httpd/conf/keytab; it must be readable by (only) the apache user. This is used for authentication by HTTP/SPNEGO, as configured in /etc/httpd/conf.d/auth_kerb.conf.
• Install the server's InCommon certificate and key files in /usr/local/shibboleth-idp/credentials/ – these are used for back-channel attribute queries by InCommon SPs, and are referenced in /etc/httpd/conf.d/idp-attr-query.conf. Make sure that they are readable by tomcat, as the idp webapp also accesses them.
• Install these additional conf files from the touchstone locker (/mit/touchstone/config/idp2-core/httpd) in /etc/httpd/conf.d:
  • auth_kerb.conf
    This configures authentication by HTTP/SPNEGO (replaces version installed by mod_auth_kerb).
  • cert-authn.conf
    This sets up the separate virtual hosts for certificate authentication on ports 446 and 447 (for certificate optional and required, respectively).
  • idp-attr-query.conf
    This sets up the vhosts for back-channel attribute queries on ports 8443 and 8444 (from MIT and InCommon SPs, respectively).
  • idp-rewrite.conf
    This adds various rewrite rules for compatibility, etc.
  • proxy_ajp.conf
    Configures the AJP proxy module for the idp webapp (replaces version installed by httpd).
  • ssl.conf (see above)
  • welcome.conf (see above)
• SELinux context mappings must be added for the non-standard ports configured for certificate authentication and attribute query, so that httpd can use them:

  # semanage port -a -t http_port_t -p tcp 446 # semanage port -a -t http_port_t -p tcp 447 # semanage port -a -t http_port_t -p tcp 8444

• 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

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/

• The MIT CA certificates must be added to the certificate trust store. This can be done by downloading and adding them explicitly to the JRE cacerts trust store, as follows:

  # wget 'http://ca.mit.edu/mitca.crt' # wget 'http://ca.mit.edu/mitClient.crt' # setenv JAVA_HOME /usr/java/latest # cd $JAVA_HOME/jre/lib/security # cp -p cacerts cacerts.orig # $JAVA_HOME/bin/keytool -import -keystore cacerts -alias mitca -file /path/to/mitca.crt # $JAVA_HOME/bin/keytool -import -keystore cacerts -alias mitclientca -file /path/to/mitClient.crt

  The password for the trust store is "changeit". Answer "yes" to the "Trust this certificate?" prompt

An already-updated cacerts store is available in the touchstone locker, in /mit/touchstone/config/java.

• 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 in /etc/init.d/, and make sure tomcat is started at boot time:

  # chkconfig --add tomcat

Install Shibboleth IdP

• You can either install the idp application from the Internet2 binary distribution and install script, by adding our local extensions and customizations to the distribution, or simply by unpacking the binary tarball from the touchstone locker into /usr/local/shibboleth-idp.
  1. To install from Internet2's binary distribution (zip file), create a build directory, unzip the file, add our login handler jar file to the lib/ subdirectory, untar the mitlogin tarball at the top of the build tree, and run the install script. Enter /usr/local/shibboleth-idp as the install target. Take the default for the hostname prompt, and enter anything for the keystore password prompt; we will override both of these in our configuration. For example (replace 2.1.5 with the appropriate version number):

     # mkdir -p $HOME/build # cd $HOME/build # rm -rf shibboleth-identityprovider-2.1.5 # unzip /path/to/shibboleth-identityprovider-2.1.5-bin.zip # cd shibboleth-identityprovider-2.1.5 # cp /path/to/shibboleth-idp-ext-MultiAuthnOptionLoginHandler-1.0-SNAPSHOT.jar lib/ # tar xzf /path/to/mitlogin.tgz # ./install.sh Buildfile: src/installer/resources/build.xml install: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Be sure you have read the installation/upgrade instructions on the Shibboleth website before proceeding. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Where should the Shibboleth Identity Provider software be installed? [/opt/shibboleth-idp] /usr/local/shibboleth-idp What is the fully qualified hostname of the Shibboleth Identity Provider server? [idp.example.org] A keystore is about to be generated for you. Please enter a password that will be used to protect it. PASSWORD ...

     This will create and populate /usr/local/shibboleth-idp; the web application (war) file will be in /usr/local/shibboleth-idp/war/idp.war. This should be copied into tomcat's webapps directory.
     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

  2. To install from a pre-installed tarball, extract our distribution tar file from the touchstone locker into the /usr/local/shibboleth-idp directory:

     # mkdir -p /usr/local/shibboleth-idp # chown tomcat:tomcat /usr/local/shibboleth-idp # cd /usr/local/shibboleth-idp # tar xzf /path/to/usr_local_shibboleth-idp.tgz

     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.in
  • authn-config.properties
  • handler.xml
  • internal.xml
  • logging.xml
  • login.config
  • relying-party.xml
  • service.xml
  • tc-config.xml (for terracotta clustering)
    You must replace %%LDAPUID%% and %%LDAPPASSWORD%% in attribute-resolver.xml.in with the principal uid (e.g. touchstone-core-service) and passord (principalCredential attribute) for accessing our LDAP server, and save the resulting file as attribute-resolver.xml. Make sure the file is not world-readable.

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

Firewall

Make sure that the additional port used by the IdP are enabled in the firewall. Use the command "iptables --list -n --line-numbers" to determine the proper rule number; the following example assumes we are inserting rules beginning at number 36. Also replace 18.x.y.z with the appropriate IP address of the peer node in the cluster, not the local host.

# iptables --list -n --line-numbers
# iptables -I RH-Firewall-1-INPUT 36 -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT 37 -m state --state NEW -m tcp -p tcp --dport 8444 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT 38 -m state --state NEW -m tcp -p tcp --dport 446 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT 39 -m state --state NEW -m tcp -p tcp --dport 447 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT 40 -m state --state NEW -m tcp -p tcp -s 18.x.y.z --dport 9510 -j ACCEPT
# iptables -I RH-Firewall-1-INPUT 41 -m state --state NEW -m tcp -p tcp -s 18.x.y.z --dport 9530 -j ACCEPT
# /etc/init.d/iptables save