Proxying the Shibboleth IdP through Apache Httpd

These instructions are intended to be read in conjunction with the UK federation's configuration guide for the Shibboleth IdP software. They are not intended to be used with software other than Shibboleth.

Tomcat

If Apache httpd is being used to proxy the IdP then Tomcat should not be listening on ports 443 and 8443. Therefore please comment out any existing <Connector> elements for port 443 and port 8443 in the Tomcat conf/server.xml file.

You will also need to ensure that the port 8009 connector is configured to accept messages proxied from Apache. In server.xml, find the port 8009 connector and edit it so that it looks like this:

 
<Connector port="8009" tomcatAuthentication="false"
     address="127.0.0.1" enableLookups="false"
     protocol="AJP/1.3" redirectPort="8443" />

Apache Modules and Proxy

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

 
ProxyPass /idp/ ajp://localhost:8009/idp/

Also, if you are using the Windows operating system then you need to find the following lines in httpd.conf and uncomment them (by removing the leading "#") to activate the necessary modules and include the SSL configuration file:

 
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule ssl_module modules/mod_ssl.so
Include conf/extra/httpd-ssl.conf

Apache VirtualHost

This assumes that you are using the standard ports 443 and 8443 for the IdP. Apache needs to be listening on both of these, so you will need these two lines in your configuration; they are usually put in httpd.conf or httpd-ssl.conf (or ssl.conf in Linux):

 
Listen 443
Listen 8443

The UK federation recommends use of a self-signed certificate for an IdP's federation trust fabric certificate. The Shibboleth IdP's installation script generates a suitable self-signed certificate, which must be configured in the <security:Credential> element in the relying-party.xml file. The certificate and key files are called idp.crt and idp.key respectively and they are stored in the credentials subdirectory of the IdP installation directory. You also need to refer to this certificate and key pair in the Apache httpd SSL configuration, if httpd is being used to proxy the IdP. In case you no longer have these files, here are instructions for creating a self-signed certificate using OpenSSL.

You should edit the Apache httpd port 8443 VirtualHost configuration to refer to the trust fabric certificate and its private key, as below. A commercial SSL certificate must be used as the browser-facing certificate to protect the port 443 SSL "endpoint" of the IdP (the URL used to access the IdP by browsers), and this is configured in the Apache httpd port 443 VirtualHost configuration as below. The VirtualHost directives are normally configured in an httpd configuration file called httpd-ssl.conf or ssl.conf. The log file locations and settings can of course be modified as necessary.

Some organisations have configured the httpd on one VirtualHost with Location directives to distinguish AA and Artifact traffic from SSO traffic. We strongly recommend you do not use that configuration, because of this SSL re-negotiation problem, and because it significantly complicates both configuration and troubleshooting.

The file names idp.crt and idp.key in the Apache configuration code below refer to your self-signed certificate. The ssl-cert.crt, ssl-cert.key and intermediate.pem files are your CA certificate file, its private key file and the CA's intermediate certificate file. The CA should have sent you the intermediate certificate file with your certificate, or made it available for download. The intermediate certificate may actually be a "bundle" of several certificates concatenated together. Please note that you should not include the CA's root certificate in the intermediate certificate bundle, because some SSL clients cannot verify the certificate chain if the root certificate is present. The intermediate certificate in the configuration given below has a .pem filename extension, but this might be different in your case. The names and locations of your files may be different, so you will need to edit this code accordingly.

You should check that the configuration options below are correct for your platform. For example, different distributions have different ciphersuites available, so you should check that the recommendations below do not specify ciphersuites which do not exist in your distribution. We also know that the SSLProtocol directives below (which are intended to specify that only the three TLSv1 protocols should be used, as other protocols are known to be insecure) are correct for Red Hat Enterprise Linux 7 or Red Hat Enterprise Linux 6.6 and later, but for other Red Hat platforms the correct directive is SSLProtocol -All +TLSv1.

 
<VirtualHost _default_:443>

ServerName idp.uni.ac.uk:443
SSLEngine on
SSLProtocol -All +TLSv1 +TLSv1.1 +TLSv1.2
SSLHonorCipherOrder On
SSLCipherSuite ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:!RC4:HIGH:!MD5:!aNULL:!EDH:!EXPORT
SSLOptions +StdEnvVars

# 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>

<VirtualHost _default_:8443>

ServerName idp.uni.ac.uk:8443
SSLEngine on
SSLProtocol -All +TLSv1 +TLSv1.1 +TLSv1.2
SSLHonorCipherOrder On
SSLCipherSuite ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:!RC4:HIGH:!MD5:!aNULL:!EDH:!EXPORT
SSLOptions -StdEnvVars +ExportCertData

# Trust-fabric certificate config
# 
SSLCertificateFile /opt/shibboleth-idp/credentials/idp.crt
SSLCertificateKeyFile /opt/shibboleth-idp/credentials/idp.key

# The next two directives ensure that the port 8443 certificate is verified by Shibboleth.
#
SSLVerifyClient optional_no_ca
SSLVerifyDepth 10

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

</VirtualHost>