|This Guide assumes|
Table of contents for step 1
Install required and recommended packages, replacing
vim with your
$EDITOR of choice (e.g.
nano, both of which also have syntax highlighting, which helps when editing XML files). Only Java will be installed from Backports (-t target release). For Ubuntu 16.04 TLS just leave out the "
-t jessie-backports" parameter and install java from the main repository (like all the other packages here):
Redirect requests to Tomcat's web root ("
/") to a URL of your choice, e.g. your institutions home page, replacing "www.example.edu" below. The Shibboleth IDP application by default will run at
/idp, allowing you to easily add other content to the webserver outside of
/idp, e.g. logos or CSS stylesheets without having them to integrate them with the "idp" context/application. The document root for that is in
/var/lib/tomcat8/webapps/ROOT/ and nothing in the software (or during use of SAML) by default links to
/ of the server, so you can use that for locally hosted content without interfering with the IDP itself. For example you will want to add a robots.txt file to prevent unnecessary scannig by search bots.
Activate the pre-configured
authbind support for Tomcat, which allows to bind to privileged TCP ports but still run the application (here: Tomcat and the complete Java Virtual Machine) as non-root, i.e. with an unprivileged user account. The default authbind setting ("
byuid", listing on "0.0.0.0") does not work when IPv6 is enabled on the system, but authbind's "
byport" works fine with both IPv4 and IPv6. So we add a file with the HTTPS port TCP/443 and change its owner to the user Tomcat is running as. The line also enabling port 80 is only for the IDP's command line utilities to work and this guide only makes port 80 available on the loopback network interface, i.e., port 80 is not and it should not be accessible from the outside!
You can verify that authbind works as intended using e.g. nc as a TCP server. Having user
tomcat8 create a server listening on port 80 fails (first example), but running the same command with
authbind should succeed:
JAVA_HOME for Tomcat and the shell (current and future ones):
Create keypair and certificate chain
Do not use an existing wildcard certificate (if one is available that would also cover your IDP webserver) – just do the work as described below and create another certificate for your IDP. Under ACOnet's TCS agreement you can get unlimited globaly valid commercial certificates. Alternatively (but not recommended for your eduID.at IDP) there's also https://letsencrypt.org/. So there should be no excuse to promiscuously share an existing TLS key pair across unrelated servers and services.
On the IDP server create an RSA private key and CSR for the web server's TLS certificate, e.g.:
Request a TLS certificate based on the CSR generated, e.g. from the ACOnet TCS. In the resulting email with the certificate there's also the CA chain file to use (e.g. called
DigiCertCA.crt). Copy the certificate and CA file to the server you're installing the IDP on (where the private key should already be, having been generated there).
Convert the TLS/SSL keypair into PKCS12
Create and note down a random password for your PKCS#12 keystore that will hold the above created TLS/SSL keypair plus the CA chain file:
Convert the TLS certificate you recieved from your CA (i.e., from DigiCert, if using ACOnet TCS), the locally generated private key and the certificate chain file into one password-protected PKCS#12 keystore file.
When asked for an "export password" set the previously generated (and noted down) password. Below you'll also add that password to the Tomcat server configuration.
Move the newly created keystore to its final location (we're chosing Tomcat's config directory) and set strict file system permissions on it:
Configure Tomcat Connector
Remove or comment out all other
/etc/tomcat8/server.xml, then add the two Connectors as per below, replacing
keystorePass with the PKCS#12 keystore password generated earlier:
Start Tomcat, check for listening ports, and access
which should result in an
HTTP Status 404 error (since /foo won't exist) but allows you to confirm a hopefully valid TLS/SSL webserver configuration.
Next validate the TLS/SSL configuration on the system itself with
Look for "Certificate chain" in the output from that command, e.g.
and verify that it looks something like the "Certificate chain" presented below. The Subject of cert 0 will obviously differ, and depending on your choice of CA or certificate product ("SSL Plus", "Unified Communications", "EV" etc.) the CA may also be different. A correct chain (and therfore PKCS#12 keystore) for TLS usage should contain all the certificates up until and excluding the root CA certificate. I..e, in the example below the certificate with
CN=DigiCert Assured ID Root CA is not included in the chain sent from the server.
In case of errors check
Tune log file creation
By default Tomcat logs additional (and duplicate) events to
/var/log/tomcat8/localhost.$date.log, which we don't care for. So let's create a backup copy of Tomcat's
logging.properties and replace its content with the minumum needed to get an access log comparable to Apache
/var/log/tomcat8/access.log, writing Tomcat's stdout/stderr to
/var/log/tomcat8/catalina.out (for debugging purposes).
Then comment out or delete the whole
Valve element at the end of your
/etc/tomcat8/server.xml, and replace it with the following one:
Then delete all Tomcat logs now and after a start only
catalina.out (which we'll keep for debugging serious IDP startup problems) and (a bit later)
access.log should be generated.
|Example server.xml file|
Find attachted to this page a minimal but working server.xml matching the above instructions. (In the next step you'll amend/replace