IDP 4 - Step 2 - Shibboleth installation

Table of contents for step 2

Install the IDP software

Before running the installer stop Tomcat and safe off the current umask of your root user's shell (so that we can later restore it) and change it to the value given below:

systemctl stop tomcat9
oldumask=$(umask)
umask 0022

The IDP installer will ask for two passwords: One to protect a newly generated PKCS#12 keystore (for a SOAP/backchannel connector, configuration of which which we've dropped from this documentation), the other as Cookie/localStorage encryption key (for client-side session storage). So generate two random strings to be used as passwords and note them down somewhere temporarily but securely, indicating their purpose (backchannel, cookie encryption). The cookie encryption password will be written to /opt/shibboleth-idp/credentials/secrets.properties by the installer (as idp.sealer.storePassword and idp.sealer.storePassword parameters).

openssl rand -hex 16  # run twice to generate two random strings

Download and unpack the latest Shibboleth IDPv4 software, adjusting the value of $VER to the latest/current version. Optional (but recommended, if you understand how PGP and the Web of Trust work) commands for verification of the software using cryptographic signatures from the Shibboleth devlopers are also included below.

VER=4.3.3
cd /usr/local/src
curl -s https://shibboleth.net/downloads/PGP_KEYS | gpg --import -
curl -O "https://shibboleth.net/downloads/identity-provider/latest4/shibboleth-identity-provider-$VER.tar.gz{,.asc}"
gpg --verify shibboleth-identity-provider-$VER.tar.gz.asc
tar xzf shibboleth-identity-provider-$VER.tar.gz
cd shibboleth-identity-provider-$VER
./bin/install.sh

When prompted:

1. Source (Distribution) Directory": Accept the current directory by hitting <Return>
2. Installation Directory: Accept the default (/opt/shibboleth-idp)
3. Host Name: Enter the publicly visible FQDN of your IDP's webserver as hostname – the one you generated a TLS server certificate for previously
4. Backchannel PKCS12 Password: Enter the previously generated password for the (to be generated, but ignored by this documentation) backchannel keystore
5. Cookie Encryption Key Password: Enter the previously generated password to protect the (to be generated) Cookie encryption key
6. SAML EntityID: Enter your current IDP's entityID or otherwise accept the default if you're installing an IDP for the first time.
7. Attribute Scope: Enter your currently used scope or otherwise the canonical DNS domain for your institution, e.g. "univie.ac.at", to be used for scoped attributes

This should result in a BUILD SUCCESSFUL message and a Web Archive file in  /opt/shibboleth-idp/war/idp.war

Optionally (only needed to make the status.sh script work) add the Java Server Tag Library to the newly installed IDP that Tomcat is not re-distributing:

cd /opt/shibboleth-idp/edit-webapp/WEB-INF/lib/
curl -sSLO "https://build.shibboleth.net/nexus/service/local/repositories/thirdparty/content/javax/servlet/jstl/1.2/jstl-1.2.jar{,.asc}"
gpg --verify jstl-1.2.jar.asc && rm jstl-1.2.jar.asc
echo | /opt/shibboleth-idp/bin/build.sh

Adjust Tomcat configuration

Since we want the IDP (and hence Apache Tomcat and the whole JVM) to be run as a non-priviledged user we'll need to adjust a couple of file system permissions:

chown tomcat /opt/shibboleth-idp/{logs,metadata}
chgrp tomcat -R /opt/shibboleth-idp/{credentials,conf}
chmod g+r -R /opt/shibboleth-idp/conf
chmod 640 /opt/shibboleth-idp/credentials/*
chmod 750 /opt/shibboleth-idp/credentials
chmod g+w /opt/shibboleth-idp/credentials/sealer.*

As per the Shibboleth IDPv3 documentation for Tomcat we'll need to make a few more adjustments:

Add a Context Deployment Fragment to Tomcat so it knows where to find the IDP's war file:

echo '<Context docBase="/opt/shibboleth-idp/war/idp.war"
    privileged="true"
    antiResourceLocking="false"
    swallowOutput="true" />' > /etc/tomcat9/Catalina/localhost/idp.xml

Following the recommendations from the Shibboleth IDPv3 wiki we also uncomment (i.e., make active) the line <Manager pathname="" /> in Tomcat's context.xml. And since we have to change that file anyway let's replace it with a minimalist version that also avoids scanning (most) of the IDP's JAR files during startup, see section Slow Startup towards the end of that Shibboleth wiki page.

cp -a /etc/tomcat9/context.xml /etc/tomcat9/context.xml.`date -u +%Y%m%dT%H%M%S`
echo '<Context>
  <WatchedResource>WEB-INF/web.xml</WatchedResource>
  <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
  <Manager pathname="" />
  <JarScanner>
    <JarScanFilter tldScan="jstl-*.jar" tldSkip="*.jar" />
  </JarScanner>
</Context>' > /etc/tomcat9/context.xml

Restart Tomcat, which may take a bit, and check the logs for WARN and ERROR messages: By default the IDP logs to /opt/shibboleth-idp/logs/idp-process.log but if something is seriously wrong and the IDP isn't even able to start up you'll have to look at Tomcat's journal entries:

systemctl restart tomcat9
multitail /opt/shibboleth-idp/logs/idp-process.log -l 'journalctl -u tomcat9.service -f'

Exit multitail with q. You can test whether the IDP is properly installed with the status command line utility:

/opt/shibboleth-idp/bin/status.sh

With these steps the installation – and therefore most of the OS-specific and GNU/Linux distribution-specific details – is done!
You can now restore a potentially deviating umask value to its previous value to close this chapter.

umask $oldumask

Now on to the configuration!