Shibboleth PKI

Shibboleth is a PKI-based system. This means that the message exchanges that flow between identity and service providers are secured using public-key technology. In practical terms, what this means is that each Shibboleth service provider must possess a private key that it keeps secret, and a public key certificate that authenticates it as a trusted service that can receive user attributes to which it is authorized. In most cases, this certificate can be self-issued and then registered, rather than signed by a particular authority ahead of time.

Unfortunately, the power of this approach is balanced by its complexity. Tools for managing keys and certificates tend to be hard to use and confusing for novices. This page explains what you need to do to get up and running securely. Shibboleth includes a command line tool from the OpenSSL package that supports a lot of different commands and options for manipulating keys and certificates.

On Unix, the openssl command is normally in the path, or will be in a bin directory beneath the location you built and installed OpenSSL. On Windows, you'll find the command in C:\opt\shibboleth-sp\bin (or wherever you installed the package). Once you reboot after installation, the command should be in the system path. able to find the libraries it needs in the system path. You should run the commands below from the etc/shibboleth directory beneath your installation root.

Automatic Key Generation

Shibboleth 2.x includes a batch/shell script that uses OpenSSL to automatically generate a keypair and self-signed certificate containing the machine's hostname. This script is run during installation on most platforms, assuming the files sp-key.pem and sp-cert.pem are not already present. To run the script by hand, simply use the keygen.bat or script directly. For older Shibboleth installs, you can download the script yourself from the source code repository.

Options can be supplied to the script to manually override the hostname used by the script, control the certificate lifetime, and overwrite an existing keypair. Use the -h option to see usage information.

If you are running multiple virtual hosts, you do NOT need to request multiple certificates. This certificate is not (generally) used to enable SSL on your web server and does not have to match the actual hostnames that might be visible to your users.

Federated Deployments and Certificate Signing Requests

InCommon (federated) deployments cannot use the default certificate generated during the SP install, as the InCommon federation requires all certificates be signed by their certificate authority.  Therefore, if (and only if) you are following the federated deployment steps, you should use the following command to generate a key and certificate signing request, in lieu of a self-signed certificate:

openssl req -new -newkey rsa:1024 -nodes -subj '/' -keyout sp-key.pem -out sp-csr.pem

In this example, you would replace with the hostname of your service. After running this command the private key would be found in sp-key.pem and the CSR in sp-csr.pem. The CSR will need to be provided during the registration process, and the signed certficate (when received) should be saved as sp-cert.pem.

Private Key Protection

Your private key is like a password for your server and needs to be both available to the software while it runs but also highly secure and inaccessible. You can see that these are competing goals. People often encrypt their keys with a pass-phrase, but since the pass-phrase has to then be stored in a file, and usually that file is backed up together with the key, nothing is gained. The best solution is to set a very strict set of permissions on the key file. Only the Shibboleth service/daemon needs access to it. You may also want to back the key up to an offline device, such as a USB dongle, and place it in a lockbox. You might then exclude the private key from your backup procedures so that it does not become vulnerable to theft by anyone with access to the tapes. You MUST protect your key.

Certificate Verification

When you're done, proceed with the configuration process for an UA-specific or federated deployment, during which you will submit the certificate you generated along with additional information about your service. During the registration process, you will be contacted and asked to run another command to compute the SHA-1 hash of your certificate so that you can repeat it over the phone and verify its authenticity:

openssl x509 -fingerprint -sha1 -noout -in sp-cert.pem

Note about Multiple Servers

If the configuration of a single application or service is spread across multiple physical web servers, you can either share a single key and certificate across all of the servers, or generate a new key on each server. Each approach has its advantages and disadvantages. Using multiple keys is more technically correct and prevents a single key compromise from preventing the use of the others. However, it creates some additional work in managing independent keys and certificates. Each certificate can be logically associated by Shibboleth with your service, so the use of multiple certificates is not a technical problem for the system itself.