IDP 5 - Step 2 - Shibboleth installation

Table of contents for step 2

Make sure Tomcat is still stopped (from the previous step) before continuing below.

Install the IDP software

Download and unpack the latest Shibboleth IDPv5 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 to verify the software using cryptographic signatures from the Shibboleth devlopers are also included below.

VER=5.1.2
cd /usr/local/src
curl -s https://shibboleth.net/downloads/PGP_KEYS | gpg --import -
curl -O "https://shibboleth.net/downloads/identity-provider/latest5/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. Installation Directory: Accept the default (/opt/shibboleth-idp) by hitting <Return>
   
2. Host Name: Enter the publicly visible host name of your IDP when accessed with a web browser – i.e., the host name you generated a TLS server certificate for previously. (This may very well be different from the "physical" hostname of the machine you're installing the IDP on.)
3. SAML EntityID: Accept the default (or dive deeper) if you're installing an IDP for the first time, otherwise enter your current IDP's entityID.
4. Attribute Scope: When installing an IDP for the first time enter the canonical DNS domain for your institution (e.g. univie.ac.at, to be used for scoped attributes), otherwise provide your currently used scope.

This should result in several log messages ending with "INFO  - Creating war file /opt/shibboleth-idp/war/idp.war" and a Web Archive file having been created in /opt/shibboleth-idp/war/idp.war

In order to make the IDP's status.sh script work (which is optional and not required for the IDP to function but may come in handy for a superficial test whether the IDP is working) add the required Jakarta Server Tag Library and rebuild the IDP Web Archive:

cd /opt/shibboleth-idp/
mkdir -p edit-webapp/WEB-INF/lib
curl -O --output-dir edit-webapp/WEB-INF/lib/ https://repo.maven.apache.org/maven2/jakarta/servlet/jsp/jstl/jakarta.servlet.jsp.jstl-api/3.0.0/jakarta.servlet.jsp.jstl-api-3.0.0.jar
./bin/build.sh

Adjust IDP log files location

You might prefer having IDP log files written to a more standard location in the file system, specifically one outside the application's own directory and on a file system where data usage is expected to grow dynamically, i.e., on /var. To do that simply set the idp.logfiles property in any of the property files read by the IDP, e.g. within conf/idp.properties:

idp.logfiles=/var/log/shibboleth

We also have to create that directory. And in order for the example commands in this documentation to work with either log directory location we'll remove the (still empty) log dir created by the IDP installer and replace it with a symlink to one we just created ourselfs:

install -o tomcat -g root -m 0750 -d /var/log/shibboleth/
cd /opt/shibboleth-idp/ && rmdir logs && ln -s /var/log/shibboleth logs

Adjust Tomcat configuration

Since we want to run the IDP (and hence Apache Tomcat and the whole JVM) 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 old 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/tomcat10/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 old Shibboleth wiki page.

cp -a /etc/tomcat10/context.xml /etc/tomcat10/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 tldSkip="*.jar" />
  </JarScanner>
</Context>' > /etc/tomcat10/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 tomcat10
multitail /opt/shibboleth-idp/logs/idp-process.log -l 'SYSTEMD_COLORS=false journalctl -u tomcat10.service -f --no-pager'

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!

Now on to the configuration!