A TrustEngine implements a TrustManagement strategy and is responsible for answering two types of runtime questions:

  • Is a signature created by a given entity valid?
  • Is a security credential presented by an entity (e.g. for SSL/TLS) valid?

While there is some overlap between them, dividing the questions this way allows for more efficiency in certain cases, but implementations can optimize themselves in whatever way is easiest.

At any given time that one of these question is asked, the issuer of the message or presumed owner of the credential must be known. Going further, the "role" in which the entity is acting must also be known, to enable entities to wield different keys when acting in different ways. This breakdown aligns with the SAML 2.0 MetaData design, which assigns key information to entity roles, not directly to entities.

Known TrustEngines

ShibOnedotThree includes a pair of "trust engine" plugins in both the IdP and SP. One is a so-called BasicTrustEngine that obtains keys directly from MetaData and does some kind of simple/direct comparison of the keys presented to it to keys found in MetaData.

The second is a ShibbolethTrustEngine that uses MetaData to "indirectly" identify certificates by name, but validates certificates using PKIX path validation rules.

Technically the SP includes a third engine, a legacy plugin that consumes a file format for defining keys and path validation rules that was created for ShibOnedotTwo. It is rather confusing to use, has not been documented, and will not be supported in future versions. Existing federations may supply information in that format until all upgrades to ShibOnedotThree are completed. It does complicate the world though.

Shibboleth 2.0 has a significantly refactored foundation that moves much/all of the TrustManagement functionality into the lower library layers, primarily so that other developers can take advantage of our innovations. The basic design is similar, though, and there is an ExplicitKeyTrustEngine and a PKIXTrustEngine (with a Shibboleth-specific extension class) that are a functional superset of the earlier BasicTrustEngine and ShibbolethTrustEngine implementations. Differences are noted.


Chaining is the ability to execute multiple trust engines in sequence to support different trust strategies. In general, the goal of chaining is to improve efficiency, by testing methods known to work faster before methods that will take longer. A significant amount of Shibboleth's performance in processing SAML messages is based on the speed of these operations.

In ShibOnedotThree, chaining is supported via the ability to configure multiple engines for a given application, and by an implicit capability in the current implementation in which more complex engines "wrap" simpler engines and automatically try the simpler approach first. This makes it relatively automatic.

In ShibTwodotZero, a special chaining trust engine is included that allows multiple engines to be connected in sequence. This is more flexible since it allows any engines to be run together, but requires that the initial configuration be done with some understanding of which engines should be run first.

What should you use?

Most deployments of Shibboleth find the inline approach simpler and less hassle to configure. Most large-scale deployments (federations, for example) rely on the PKIX approach today, but we expect this to change as people become more comfortable with the idea that signed MetaData is effectively like a bulk certificate authority, and because many SAML 2.0 features will require out of band knowledge of actual keys, and not just validation of certificates.

However, it is nevertheless true that while Shibboleth may offer reasonably scalable approaches to use of MetaData as a key distribution and revocation strategy, other SAML products may not. Be aware that what works well for Shibboleth may not work well for other implementations.