Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The IdP also makes use of cryptography in ways that you'll need to understand in at least a rudimentary way because the security of everything you do with the IdP depends upon it.

Table of Contents

Java Container Considerations


By default, most Java containers are provided with some kind of HTTP connector/listener on ports 8080 and 8443. This is because non-Windows operating systems restrict processes from binding to ports under 1024 unless they run as root. Some newer systems have more advanced policy control over this.


Privileged Ports

If you choose to run a Java-based web server by itself (without Apache or the like), the first thing you'll need to do is to prepare an environment for it to run under a non-root account but allow use of port 443 and possibly 80 (optional) using a technique such as a setuid mechanism or port forwarding. Don't skip this step and don't worry about the IdP until this is done. Your overall experience will be much more confusing and painful if you ignore this advice.


Using Apache as the web server is possible, though discouraged, with two conditions:

  • You typically want to be using an AJP-based proxy connector to your Java container, because only AJP allows the client certificate to be passed into the Java server so the IdP can evaluate it. Failing this, you will have to ensure that any requests are made with signed messages.

  • You must set the option SSLVerifyClient optional_no_ca in your back-channel virtual host configuration.

The latter works, but is subject to certain limitations that will cause problems for some SPs because even when this option is used, the Apache module still applies some restrictions on the client certificate that are not strictly required by the IdP itself. So this will limit the interoperability of your deployment.


There are a number of different keys and certificates used by the IdP, each for a specific purpose. Most are holdovers from earlier versions (which is noted where appropriate) but a couple of the use cases are new and therefore introduce some different scenarios to be aware of.


Read the general topic on SAML Keys and Certificates before reading this section.

Your IdP Keys and Certificates


As always, you have to install a private key and certificate on the server to enable TLS to encrypt the traffic from clients (and nominally, but in reality just a fiction, to authenticate the server to the browser client). This is generally going to require a commercially-issued certificate rooted in a CA all browsers will trust. Make sure that you can change this key and certificate any time you care to or need to.


Use of browser-facing TLS key and certificate

This key and certificate is not used by Shibboleth directly, and you SHOULD NOT use this key (or certificate) in any of the other capacities described below. Doing so will unnecessarily complicate the management of your system and lead to frequent key rollover events, which are among the most expensive operations you will undertake in a federated deployment.

This is not a change from V2 or V3.


The main key underlying most IdPs is the digital signing key. This is a private key used to sign SAML messages.


Protect your private signing key!

Make no mistake, a compromised signing key allows anybody with the key to impersonate your IdP and by extension all of its users.

The installer (when not upgrading an older installation) will generate a private signing key and a long-lived, self-signed certificate containing the public key. The certificate is just a convenient container for the public key. In Shibboleth, or any compliant SAML system, the content of the certificate other than the key is totally ignored.


Some SPs may have private keys and certificates used for one or more of the following:

  • Signing SAML requests (or, in a few cases such as Single Logout, SAML responses)

  • Client or server authentication of back-channel SAML requests or responses (SOAP primarily)

Signing-only certificates are communicated via a <md:KeyDescriptor use="signing"> element in SP metadata. When configured in the usual fashion, the IdP will completely ignore the content of the certificate other than the public key, but in a back-channel scenario the web server may or may not ignore the certificate's content depending on the software and configuration involved (discussed above).


While an SP may advertise any number of encryption certificates in its metadata, the IdP will pick only one to encrypt with, and it is generally non-deterministic at times which one is used. This means an SP cannot put different keys on different servers as part of a cluster of servers (the IdP won't know which one to pick), and it complicates changing the encryption key because the SP must be able to support decrypting data with both the old and new keys at once (Shibboleth can, but not every implementation can).

Metadata Signing Keys and Certificates

A final type of key you may encounter is one used to digitally sign SAML metadata. Shibboleth differs from most SAML implementations in that it favors the use of third-party sources of metadata (informally termed "federations") to vouch for the information supplied, much like a traditional certificate authority signs certificates. The public key certificate used to verify a signed metadata file is essentially a trust anchor, like a CA root certificate.