Getting Certificates for a Shibboleth 2.x IdP installation

To set up a Shibboleth 2.x IdP entity within the UK federation you will normally require two X.509 digital certificates:

• a trust-fabric certificate for machine-to-machine use, and
• a browser-facing certificate that users will see

These two certificates are used for different purposes and have different properties:

• A self-signed certificate with a lifetime of 10 or 20 years is recommended for the trust fabric certificate
• An SSL certificate from a commercial Certification Authority (CA) is required for the browser-facing certificate

A key length of 2048 bits is recommended for all certificates, and a key length of at least 2048 bits is mandatory for trust fabric certificates. We recommend 2048 bits, as longer keys provide no additional practical security but are more computationally expensive for all parties.

Acquiring a Shibboleth 2 IdP trust-fabric certificate

For a new installation

You do not normally need to take any action to acquire a trust-fabric certificate for a new installation, as a suitable certificate is generated automatically by the Shibboleth 2.x IdP installation script. The files created are a certificate, a private key, and a Java keystore file, called idp.crt, idp.key, and idp.jks respectively, and they are stored in the credentials subdirectory of the Shibboleth IdP installation directory. (See the section Certificate credentials in our Shibboleth 2 IdP configuration guide for further details.)

Replacement for an existing installation

If you need to create a new certificate and key pair because the current one is due to expire, or needs to be replaced for any reason, and the certificate and key pair that were created at installation have since been deleted or overwritten, then you can use the renew-cert option to the install.bat or install.sh installation script.

You should always take back-up copies of the current certificate and key or keystore files before running renew-cert to protect against the possibility of their being overwritten.

Versions earlier than 2.3

The renew-cert option is only available in versions of the installation script shipped with versions 2.3 and higher of the Shibboleth IdP software. However, you can download the .zip archive of a recent V2.4.x release in of the Shibboleth IdP software, unpack it, and use the install.sh or install.bat with the renew-cert option to create the key pair. You don't need to install the IdP software to do so.

Important note: all versions of the Shibboleth IdP software up to and including 2.4.3 are now end-of-life. We recommend for security reasons that you upgrade your Shibboleth IdP deployment to the most recent version of the software as a matter of priority.

Also as an alternative to renew-cert we have documented the creation of a self-signed certificate and key pair using openssl.

Replacing a Shibboleth 2 IdP trust-fabric certificate

A trust fabric certificate should be replaced before it expires. Please note that this process may take several days or weeks, so plenty of time should be allocated especially if you are unfamiliar with the process.

We recommend you follow these steps:

1. email the new certificate to us and ask us to add it to the registered IdP metadata in the federation in addition to the old one. Please do not send us the private key.
2. wait for a few days to allow the metadata to propagate to federation SPs
3. then configure the IdP software to use the new trust fabric certificate. There are two places in which the certificate must be configured:
   • in the IdP conf/relying-party.xml file
   • and in the port 8443 configuration in Tomcat (or other Java servlet container), or in Apache as appropriate
4. it's also advisable to replace the old certificate contents in the metadata/idp-metadata.xml file with the new certificate wherever it occurs, because the Shibboleth IdP software does not automatically update the file. This is useful as a record of the IdP's registered metadata for your own reference, but has no effect on operation, as the IdP software never checks the certificate in the idp-metadata.xml file.
5. test using the UK federation test SP and check in your IdP log that the IdP is using the new certificate. You need the PROTOCOL_MESSAGE logger at DEBUG as described in our Shibboleth IdP documentation. Please note that the IdP only logs the contents of the certificate configured in relying-party-xml, not the one configured on port 8443.
   
   If you can't tell which certificate it's using then please ask the UK federation support team to check the test SP log for you.
6. ask us to remove the old certificate from the metadata

Please note: There should be no loss of service with most federation SPs if the above procedure is followed. However there are some SPs that are unable to handle the presence of more than one certificate in an IdP's metadata, so please keep the time that you have two certificates in metadata as short as possible.

Acquiring and replacing a browser-facing certificate

Here are details of acquiring a browser-facing certificate.

The browser-facing SSL certificate does not appear in metadata (unless it happens also to be the trust fabric certificate). It needs to be configured in the port 443 SSL VirtualHost in Apache or in the port 443 Connector in Tomcat as appropriate.