...
Java servlet applications run in so-called Java containers, such as Jetty, Tomcat, JBoss, or Glassfish. Most servlet containers are themselves web servers, and have sufficient features, flexibility, and performance to support most deployments, at scale, without the use of a separate web server like Apache. The IdP also occasionally (though far less often these days) requires certain web server features that are easier to support when Jetty or Tomcat are used alone than other containers or non-Java web servers, which will be discussed further below.
In cases where use of a native web server is required, this is typically done by "connecting" the native web server to the container using either the AJP protocol (recommended where possiblewith Tomcat) or by HTTP reverse-proxying. In this case, the container generally must be configured to receive connections only from the native web server and failure to limit this will lead to significant security risk.
...
Historically, Shibboleth IdP deployments have operated with a second HTTP connector for SOAP requests from Service Providers. This connector by convention usually listens listened on port 8443. The separate port is was used primarily because the connector has generally relied on client certificate authentication at the TLS layer to authenticate requests from SPs. It's possible to host these SOAP services on the same port as the rest of the IdP's services and this is usually recommended nowadays, but this used to require changes to SP configuration, so is beyond the scope of this introductory topictopic focuses on the "why" aspect.
Back-Channel Use Cases
Most newer SAML-only deployments do not need to support the back channel. While there are a range of features that rely on the back channel, and probably more in the future, basic use of the IdP for SAML-based SSO does not require it. That said, the following features require a back channel, along with a brief explanation of why you might need them.
...
SAML queries for attribute data are were historically common in the Shibboleth world because the earliest versions based on SAML 1.1 relied on an attribute query to request attributes after processing a SAML 1.1 SSO response delivered by the browser. This is was to avoid including attributes up front because SAML 1.1 does did not allow for data to be encrypted, allowing it to be observed passing through the client.
Newer deployments may generally will not require support for SAML 1.1 at all, since most the vast majority of SPs today have support for SAML 2.0. Even if you do need to support SAML 1.1, you may not consider the exposure of data in the browser to be a major consideration, depending on the sensitivity of the attributes. You could choose to enable so-called "attribute push" by including the attributes with SSO by enabling the includeAttributeStatement profile configuration option.
Most deployments do not need support for SAML 2.0 attribute queries, though they are also supported. In most cases it's advisable not to advertise support for that feature in your metadata. Including it when unneeded can cause some wasted traffic from Shibboleth SPs if you happen to issue a SAML 2.0 response to one that includes no attributes. In some cases, a redundant SAML 2.0 attribute query can cause a spurious error at the SP.
...
The Artifact feature in SAML is a pass-by-reference approach to the exchange of a SAML SSO assertion that relies on a redirect to the SP with a small artifact string that is "resolved" by sending a SOAP request to the IdP. Ordinarily, the default SAML flow used in Shibboleth is a POST to the SP in which the assertion is pushed in the body of a form. The primary advantage of the artifact approach is that it handles cases where an unprotected page includes embedded references to images or other content that are protected. It also has security properties that are considered to be an advantage by some people .Artifact due to the widepread lack of adoption of proper metadata support in SAML software.
Artifact usage is not common today, and it introduces complications when clustering an IdP and when testing upgrades or configuration changes. If not supported, it's very important for correct operation of SPs that your metadata not include the endpoints that indicate support for this feature.
...
Support for SOAP logout does require that the session store be on the server side, which is not the V3 default, and greatly complicates clustering. As a result, this isn't a feature likely to matter very much in most cases.
Other Protocols
Most of the non-SAML protocol support in the IdP does tend to rely on a back-channel, but these features were designed from the ground up to operate over port 443.
Back-Channel Support Implications
If you do decide you need to support the back channel on a different port, then the one complication is to be able to accept any certificate presented by an SP. Most implementations of TLS certificate authentication in web servers are primitive at best and broken at worst, and have to be "convinced" to allow this.
...
When Java containers are used to handle this traffic, it is typical to require some kind of Java plugin to override the certificate handling. For containers that are formally supported, the installation pages for each container will include a reference to a plugin component and information on how to configure it. For other containers, you will be on your own and may need to forgo supporting the back channel on a separate port.
Apache
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, and that isn't a default of Shibboleth SPs at the moment..
- You must set the option SSLVerifyClient optional_no_ca in your back-channel virtual host configuration.
...
The following summarizes all of the keys and certificates that are part of the operation of an IdP.
| Warning |
|---|
It is the responsibility of the IdP operator to securely manage all private keys. |
Browser-facing TLS Server Key and Certificate
...
The use of the front-channel exclusively in SAML was based on the assumption that software would implement the standard in full, and address the need for key management and revocation through support for constant update of verified metadata. This did not occur, and as such, much of the non-Shibboleth software world of SAML is a broken mess of insecure practice and total lack of practical security measures to deal with the compromise of an IdP's key. As such, if your key is compromised and you operate an IdP at scale, you are facing months of painful work to recover. |
Browser-facing TLS Server Key and Certificate
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.
...
This is not a change from V2 or V3.
Lifecycle
The browser-facing key typically changes annually or semi-annually, and increasingly tends to be managed as part of a load balancer environment rather than on the IdP servers.
...
| Warning | ||
|---|---|---|
| ||
| Make no mistake, a compromised signing key allows anybody with the key to impersonate your IdP and by extension all of its users. |
The V3 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.
The certificate is communicated via a <md:KeyDescriptor use="signing"> element in SAML metadata. The use XML attribute is important, as will be made clear below.
In a non-updated new install of V4 or an upgrade from V3 or later, the generated signing key pair will be prefixed idp-signing (the names can be overridden if desired via the idp.properties file).
In V2, the generated signing key pair was named idp.key and idp.crt (the names typically configured via relying-party.xml). An upgraded install of V3 will maintain maintained the V2 approach and files by default, carrying over to future upgrades.
Lifecycle
This keypair ideally never changes outside of a catastrophic event. If your policies require you to change it, you should budget a large amount of time from the IdP operations team and all of your affected customers to coordinate the change, or you will need to accept a significant amount of service disruption. Some disruption is also unavoidable in most deployments even if you do everything correctly.
...
| Tip |
|---|
This section only applies should you choose to operate the IdP over the second a separate back-channel port, but can be ignored otherwise. |
...
The deployment of this key and certificate involves your web server, rather than the IdP application, so actual configuration of this key is outside the scope of this documentation. And of course if you don't need to support the back channel on a separate port, then you can ignore this key pair.
The V3 installer (when not upgrading an older installation) will generate a key pair to use for your back-channel TLS configuration. The As with the signing key above, this certificate is also communicated via a <md:KeyDescriptor use="signing"> element in SAML metadata. (The use="signing" XML attribute refers to authentication generally, which includes back-channel TLS.) While most of the content of this certificate is ignored by Shibboleth SPs, the name of the server hosting the TLS endpoint does have to match the certificate's CommonName or a subjectAltName extension, following usual TLS practice. The installer does this for you automatically as best it can.
The older practice of using the same key for both digital signing and back-channel TLS is still obviously permitted but is discouraged to limit key usage to specific purposes, which is a more secure practice. In particular, there are many more known attacks in recent years that have compromised TLS server keys than on keys used "behind the scenes".
In a non-updated install of V3new install, or upgrade of a V3+ install, the generated back-channel key pair will be prefixed idp-backchannel but the files are not explicitly referenced by the IdP configuration because they are meant for use by the container to configure its back-channel TLS connector/listener.
In V2, the back-channel key pair was also not part of the configuration but conventionally was the same as the signing key pair. An upgraded install of V3 will did not generate a new key pair and is was generally assumed to be reusing the existing back-channel configuration choices.
...
Encryption Key and Certificate
A third key pair, new to this version V3 and subsequent versions of the IdP, supports inbound XML Encryption. The private key is used to decrypt data encrypted under the public key. The latter is bound to a certificate that is communicated via a <md:KeyDescriptor use="encryption"> element in SAML metadata.There are only a few scenarios in which SPs are likely to need to encrypt data transmitted to the IdP and none of them are common. The most likely use case would be to encrypt the subject of a SAML logout request but Shibboleth SPs (and most other implementations) don't do this by defaultis used to decrypt data encrypted under the public key. The latter is bound to a certificate that is communicated via a <md:KeyDescriptor use="encryption"> element in SAML metadata.
There are only a few scenarios in which SPs are likely to need to encrypt data transmitted to the IdP and none of them are common or essential. The most likely use case would be to encrypt the subject of a SAML logout request but Shibboleth SPs (and most other implementations) don't do this by default.
| Tip |
|---|
We strongly advise against use of non-transient NameID values in all SAML deployments in all cases to minimize or outright avoid any need for IdP decryption. SAML Attributes are a better choice for communicating information about subjects, and transient NameIDs can be used for SAML logout purposes without imposing requirements for encryption to protect the appearance of PII in web server logs. |
While it's been common practice with in the past for the Shibboleth SP to generate a single key pair for both signing and encryption, the IdP V3 installer generates a separate key pair for each, again for "best practice" reasons. It is particularly advisable to separate out the encryption key pair at the IdP because it has very different security properties. Compromising a decryption key allows data to be exposed (but not forged) in relatively rare cases while compromising the other keys is fatal to the security of the entire system.
Note that advertising a certificate in metadata with no use XML attribute is an indication that the same private key is used for both signing and decryption. After an upgrade, you may have older IdP metadata needing correction that mistakenly indicates this.
In a non-updated install of V3new install, or upgrade of a V3+ install, the generated encryption key pair will be prefixed idp-encryption (the names can be overridden if desired via the idp.properties file).
In V2, this functionality did not exist and so no allowance for this existed in the configuration. An upgraded install of V3 essentially defers deferred the timing of having such a key pair and some adjustments have had to be made at some point later on. If you want to perform an An upgrade using a clean install to start with, and using the generated key pair is fine as long as you adjust , requires adjusting your IdP's metadata shared with every SP to reflect the use of a separate key pair for this function, as noted above. Doing this while publishing metadata containing a certificate in metadata with no use XML attribute will cause problems.
...
A fourth key, also new to this version of the IdPV3 and later, is an AES secret key used to secure cookies and certain other data by the IdP for its own use. This key is never shared with anybody else and is copied (or made accessible) to every server making up a cluster.
...
While an SP may advertise any number of encryption certificates in its metadata, the IdP will pick only one to encrypt with, typically the first certificate it finds that is suitable (almost always just the first one listed, barring some unusual cases)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).
...