Certificates in a Shibboleth 2.x SP installation

A Shibboleth 2.x SP entity will normally require two X.509 digital certificates:

  • A browser-facing certificate. This is a typical TLS certificate which is issued by a Certificate Authority and which is required for HTTPS-protected sites.
  • A trust fabric certificate. This is for machine-to-machine use, and will be published by the UK federation in our metadata. We recommend a self-signed certificate with a lifetime of 10 or 20 years.

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. Keys longer than 2048 bits provide no additional practical security but are more computationally expensive for all parties.

Acquiring a Shibboleth 2 SP trust-fabric certificate

You do not normally need to take any action to acquire a trust fabric certificate, as a suitable certificate and key pair is generated automatically by the Shibboleth 2.x SP installation script. These are named sp-cert.pem and sp-key.pem respectively, and are in the Shibboleth SP installation directory or folder (See the section on Trust Fabric Certificates in our Shibboleth 2 SP configuration guide).

If you no longer have the certificate and key pair generated at installation, or you need to create a new certificate and key pair for some other reason, then you can use the keygen script which is in the service provider installation directory; it will be called keygen.sh or keygen.bat depending on the operating system. Use the -h option to see usage information.

If you do not have keygen then you probably have a very old version of the SP software, and it's strongly recommended for security reasons that you upgrade as a matter of priority. But as an alternative to keygen we have documented the creation of a self-signed certificate and key pair using openssl.

Replacing a Shibboleth 2 SP trust-fabric certificate

A trust fabric certificate should be replaced before it expires. When replacing an embedded Shibboleth 2 SP trust fabric certificate we recommend that you follow the steps described on the Shibboleth 2 SP documentation site under "Key Rollover". These changes are required in the file shibboleth2.xml. Please note that this process may take between several days and several weeks so that updated metadata can propagate to federation IdPs, so plenty of time should be allocated. If you aren't familiar with the process then allow at least a month.

To summarise the process:

  1. add the new certificate and key to your SP configuration with use="encryption", as in step 1) at the Shibboleth link above. You must ensure that the SP picks up the new configuration, for example by restarting the SP. You can check that the new certificate is being used, by querying the SP's metadata handler at https://...your sp's domain.../Shibboleth.sso/Metadata and checking that the new certificate is present with use="encryption" in addition to the old certificate.
  2. ask the UK federation support team to add the new certificate to the SP metadata in addition to the old one. This request must be authorized, usually the SP's administrative contact. We perform certificate verification with that person. You should then wait for a few days to allow the metadata to propagate to federation IdPs.
  3. switch use="encryption" in the SP configuration from the new key to the old key, as in step 3) at the Shibboleth link. Ensure the running SP is using the updated configuration.
  4. ask the UK federation support team to remove the old certificate from the metadata, and wait another few days to allow the metadata to propagate.
  5. remove the old key pair from your SP configuration.

There should be no loss of service if that procedure is followed.

Please note that if your SP is registered in multiple federations, then you will need to ensure that any certificate replacement is co-ordinated across federations.

Acquiring a browser-facing certificate

Here are details of acquiring a browser-facing certificate.