New Linux deployment

Linux operators deploying from scratch will need to determine whether to use the Tomcat or the Jetty container and follow the instructions here in conjunction with those at the appropriate links in the "Non-Windows Installation" section of the installation page to set up their chosen container and install the software.

This documentation here is being written using the CentOS 7 Linux distribution as the test platform. The Shibboleth IdP installation documentation for Linux is here.

Privileged port 443

The IdP software requires use of the privileged https port 443; this means that Linux deployers need to find a way of handling this without running the Java servlet container as root, which is insecure.

Proxy through load balancer or Apache

If you proxy through a load balancer or through Apache httpd then the servlet container can use an unprivileged port and run as an unprivileged user; and the load balancer or Apache can handle the external traffic to and from port 443. Apache switches to non-root operation at completion of start-up so does not suffer from the same issue.

Other mechanisms

Other possibilities include a setuid mechanism or port forwarding. The Shibboleth wiki provides links to information for Tomcat, Jetty 9.4, and Jetty 10.0.

Apache web server

It is no longer necessary to proxy the Shibboleth IdP through Apache httpd, and has not been since Shibboleth IdP v2.x onwards. However, for various reasons, such as easier certificate management and operation of privileged ports, many deployers prefer to use the Apache httpd web server as a proxy, so we continue to provide some guidance for this, as well as for deployment in a standalone Java servlet container.

Most deployers proxying through Apache prefer to use the Tomcat servlet container, so we focus on the Apache httpd with Tomcat combination here. For those wishing to use Apache httpd in combination with the Jetty container, there is some configuration advice in the Shibboleth wiki.

Apache configuration

You will need to edit the Apache httpd configuration file httpd.conf to configure Apache to pass requests for "/idp/" to the Java servlet container, which we will ensure listens on localhost port 8009. Add this line to the end of the file: 

 ProxyPass /idp/ ajp://localhost:8009/idp/
Apache port 443

Apache needs to listen on port 443: 

 Listen 443

In the following VirtualHost configuration you configure your IdP server's fully qualified domain name, your browser-facing certificate file, intermediate certificate(s) file and private key file (all in PEM text format), TLS settings, and logging settings. 

 <VirtualHost _default_:443>

   ServerName idp.example.ac.uk:443
   SSLEngine on
   SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 -TLSv1.2
   SSLHonorCipherOrder On
   #
   # SSL certificate config
   #
   SSLCertificateFile /opt/shibboleth-idp/credentials/ssl-cert.crt
   SSLCertificateKeyFile /opt/shibboleth-idp/credentials/ssl-cert.key
   SSLCertificateChainFile /opt/shibboleth-idp/credentials/intermediate.pem

   ErrorLog logs/ssl_443_error_log
   TransferLog logs/ssl_443_access_log
   LogLevel warn
   CustomLog logs/ssl_request_log "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

 </VirtualHost>

Important note: the configuration above is informed by, but not identical to, the one recommended at the Mozilla link below for a "modern" configuration at the time of writing. We do not guarantee it represents current good practice at the time you are reading this document. You should research current good practice for TLS settings and adjust the configuration accordingly.

We think that it is better to have SSLHonorCipherOrder On to allow the server to force the client to use the best ciphersuite supported by both client and server.

Mozilla SSL Configuration Generator (Apache, Modern)
Tomcat configuration with Apache proxy

Ensure that Tomcat is not listening on any ports except port 8009 by commenting out all <Connector> elements in the Tomcat server.xml file. Modify the port 8009 <Connector> as necessary so it looks like this: 

 <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" secretRequired="false" />

The secretRequired setting strictly speaking is only needed when the proxy traverses a network.

Install Java

Using the Linux distribution's package manager (yum, dnf, apt etc) is the most convenient way to manage the available Java.

First check which version is currently installed: 

 $ java -version
 openjdk version "1.8.0_262"
 OpenJDK Runtime Environment (build 1.8.0_262-b10)
 OpenJDK 64-Bit Server VM (build 25.262-b10, mixed mode)

If you need to upgrade then find the appropriate package name using the package manager's search function:

  • CentOS / RedHat: yum search openjdk
  • Debian / Ubuntu: apt-cache search openjdk

When you've found the package, install it using the package manager. Below are some examples but check first: 

 # CentOS / RedHat 
 yum install -y java-11-openjdk

 # Debian / Ubuntu
 apt-get install -y openjdk-11-jdk

Verify the new version is being used by default: 

 $ java -version
 openjdk version "11.0.8" 2020-07-14
 OpenJDK Runtime Environment (build 11.0.8+10-post-Ubuntu-0ubuntu118.04.1)
 OpenJDK 64-Bit Server VM (build 11.0.8+10-post-Ubuntu-0ubuntu118.04.1, mixed mode, sharing)

If the install process has not enabled it as the default then you will need to use the update-alternatives system to select it: 

 update-alternatives --config java

Install Shibboleth

1. Visit https://shibboleth.net/downloads/identity-provider/latest/ and get the URL for the .tar.gz file (currently https://shibboleth.net/downloads/identity-provider/latest/shibboleth-identity-provider-4.2.1.tar.gz)

2. Download the new release to the server: 

 cd /usr/local/src
 curl -O https://shibboleth.net/downloads/identity-provider/latest/shibboleth-identity-provider-4.2.1.tar.gz

3. Extract the new release: 

    tar xf shibboleth-identity-provider-4.2.1.tar.gz

4. Run the installer for the new release: 

 cd shibboleth-identity-provider-4.2.1
   ./bin/install.sh

5. Ensure the correct default responses have been generated for the release location and deployment location (either press ENTER to accept or enter the correct location)

Install and configure Java servlet container

The popular containers are Tomcat and Jetty. The Shibboleth project does not officially support packaged containers; but in practice we have not seen issues with containers packaged with popular Linux versions. However you use them at your own risk. Please see the documentation for your Linux distribution for installation and upgrade documentation if you decide to use a packaged container.

We provide manual installation guidance here for Tomcat and Jetty; you need only one of these; you should choose one based on your requirements and environment.

Jetty installation and configuration

Please see our upgrade documentation for manual Jetty installation information and instructions for deployment of the Shibboleth jetty-base. Instructions are given there for configuration of the browser-facing certificate and the back-channel certificate; please note that the back-channel certificate configuration is not required unless you plan to use the deprecated SAML 1 protocol.

Tomcat installation and configuration

Please see our upgrade documentation for manual Tomcat installation information.

We provide the configuration here for the HTTPS "virtual host" with browser-facing certificate configuration: 

 
    <Connector port="443"
               protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150"
               SSLEnabled="true"
               scheme="https"
               secure="true"
               keystoreFile="/opt/shibboleth-idp/credentials/idp-browser.p12"
               keystorePass="privatekey"
               keystoreType="PKCS12"
               clientAuth="false"
               honorCipherOrder="true"
               sslProtocol="TLSv1.3" />

Important note: the configuration above is informed by, but not identical to, the one recommended at the Mozilla link below for a "modern" configuration at the time of writing. We do not guarantee it represents current good practice at the time you are reading this document. You should research current good practice for TLS settings and adjust the configuration accordingly.

We think that it is better to have SSLHonorCipherOrder On to allow the server to force the client to use the best ciphersuite supported by both client and server.

Mozilla SSL Configuration Generator (Jetty, Modern)