Page Comparison

Enablement

For most situations, the default behavior of each ProfileConfiguration is appropriate when it comes to what to sign or encrypt. A common use case for creating overrides for particular relying parties is to either turn off XML Encryption, or possibly alter which part of a SAML message is to be signed. This is controlled with a set of properties on all SAMLProfileConfiguration and SAML2ProfileConfiguration objects, each of which is a condition that evaluates to true or false to determine what to sign or encrypt.

In most cases, you can set the properties to "true" or "false" to turn them on or off. An example follows:

Per-Profile Signing or Encryption Options

<!-- excerpt of relying-party.xml -->

<bean parent="RelyingPartyByName" c:relyingPartyIds="https://sp.example.org">
    <property name="profileConfigurations">
        <list>
            <bean parent="SAML2.SSO" p:signAssertions="true" p:encryptAssertions="false" />
        </list>
    </property>
</bean>

For more advanced scenarios, you can configure an arbitrary condition function to control the decision. Most commonly this would be used in conjunction with a built-in condition that works by deciding whether to sign or encrypt based on the security of the underlying communication channel. This isn't typically needed, but an example follows:

Conditional Signing or Encryption

<!-- excerpt of relying-party.xml -->

<bean id="SignNoIntegrity" class="org.opensaml.profile.logic.NoIntegrityMessageChannelPredicate" />
<bean id="EncryptNoConfidentiality" class="org.opensaml.profile.logic.NoConfidentialityMessageChannelPredicate" />

<bean parent="RelyingPartyByName" c:relyingPartyIds="https://sp.example.org">
    <property name="profileConfigurations">
        <list>
            <bean parent="SAML2.SSO" p:signAssertions-ref="SignNoIntegrity"
                p:encryptAssertions-ref="EncryptNoConfidentiality" />
        </list>
    </property>
</bean>

Finally, a new feature exists to do encryption "opportunistically", that is, to encrypt whenever possible (meaning a compatible key is found in the peer's metadata to encrypt with) but to skip encryption otherwise. For those wishing to avoid having to constantly adapt their system to deal with new services that don't support encryption, this is an option you can use, understanding that this means a loss of explicit control over whether XML Encryption takes place. This feature is enabled with the idp.encryption.optional property.

Configuration

There are several levels of SecurityConfiguration objects to control the signing, validation, encryption, and decryption processes. These configurations include things like the keypairs to use, preferred/default algorithms, and algorithm allow or deny lists to enforce. The configurations can be derived from the underlying library defaults, a global IdP default, or a per-profile override.

In most cases you will leave the defaults in place, or very occasionally define a special configuration to use for specific profiles and/or relying parties.

The default objects that make up these configurations are defined in a system file and are defined to match the defaults in the OpenSAML libraries. You can't modify these beans, but they do document the full range of wiring up of settings that's possible. You can inherit from some of them in order to override specific bits and leave the other defaults in place, which is simpler than creating an entire SecurityConfiguration object from scratch.

You can override the default bean name that is used as a global default by setting the idp.security.config property. That effectively ignores the system-defined objects in favor of something else. You can also override this on a per-profile, per-relying-party basis by adding a p:securityConfiguration-ref attribute to a profile bean.

The (formerly common) case of controlling the use of SHA-1 and SHA-256 digest algorithms while signing is simplified because we have predefined beans that toggle between those two algorithms at a global level, with a property to switch between them (idp.signing.config).

Similarly, there are predefined beans for toggling between two data encryption families, AES-CBC and AES-GCM. The former is widespread and well-supported, and vulnerable to attacks that can reveal the data. The latter is not widely supported but is the only practical algorithm that remains secure. A new property will switch between them globally (idp.encryption.config) but in practice that won't work all that well because so many SPs will not support GCM (though that should be considered non-compliant with any modern support for the standard).

The following is an example to follow if you need to specify the use of SHA-1 instead of SHA-256 for a specific relying party.

Per-Profile Signing Algorithm

<!-- excerpt of relying-party.xml -->

<util:list id="shibboleth.RelyingPartyOverrides">

  <bean parent="RelyingPartyByName" c:relyingPartyIds="https://sha1only.example.org">
    <property name="profileConfigurations">
        <list>
            <bean parent="Shibboleth.SSO" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML1.AttributeQuery" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML1.ArtifactResolution" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML2.SSO" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML2.ECP" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML2.Logout" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML2.AttributeQuery" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
            <bean parent="SAML2.ArtifactResolution" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.SHA1" />
        </list>
    </property>
  </bean>

</util:list>

Similarly, you can do the same with encryption for GCM:

Per-Profile Encryption Algorithm

<!-- excerpt of relying-party.xml -->

<util:list id="shibboleth.RelyingPartyOverrides">

  <bean parent="RelyingPartyByName" c:relyingPartyIds="https://sha1only.example.org">
    <property name="profileConfigurations">
        <list>
            <bean parent="Shibboleth.SSO" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML1.AttributeQuery" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML1.ArtifactResolution" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML2.SSO" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML2.ECP" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML2.Logout" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML2.AttributeQuery" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
            <bean parent="SAML2.ArtifactResolution" p:securityConfiguration-ref="shibboleth.SecurityConfiguration.GCM" />
        </list>
    </property>
  </bean>

</util:list>

A more advanced case: to specify a custom keypair for signing for a particular relying party, you might create a bean in credentials.xml called "ObnoxiousVendorCredential", and then do the following (there are many ways to lay things out, this is just an example of what's possible):

Per-Profile Credential

<!-- excerpt of relying-party.xml -->

<bean id="ObnoxiousSecurityConfig" parent="shibboleth.DefaultSecurityConfiguration">
	<property name="signatureSigningConfiguration">
		<bean parent="shibboleth.SigningConfiguration.SHA256" p:signingCredentials-ref="ObnoxiousVendorCredential" />
	</property>
</bean>

<util:list id="shibboleth.RelyingPartyOverrides">

  <bean parent="RelyingPartyByName" c:relyingPartyIds="https://obnoxious.vendor.com/sp">
    <property name="profileConfigurations">
        <list>
            <bean parent="Shibboleth.SSO" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML1.AttributeQuery" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML1.ArtifactResolution" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML2.SSO" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML2.ECP" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML2.Logout" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML2.AttributeQuery" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
            <bean parent="SAML2.ArtifactResolution" p:securityConfiguration-ref="ObnoxiousSecurityConfig" />
        </list>
    </property>
  </bean>

</util:list>

Typically you want to think about what you need to customize, and then consolidate definitions of beans as much as possible to simplify the XML.

TrustEngines are a type of object used to evaluate signatures and TLS certificates and make up the security backbone of the IdP. This defaults to a "chain" of two strategies:

• looking for a matching public key inside SAML metadata corresponding to a message issuer

• verifying a certificate indirectly by performing PKIX path validation, generally against trust rules supplied in SAML metadata extensions defined by the Shibboleth Project many years ago

The recommended approach is the first one. The second is provided solely for compatibility and while it is used by some deployers, we expect to eventually disable it by default in a future release. It is not deprecated, but it is not a recommended choice.

In the event that you wish to replace the "chain" with a reference to one of the TrustEngines alone, you can set one or both of the idp.trust.signatures and idp.trust.certificates properties in idp.properties to appropriate bean names (noted below and in the property file's comments).

The last area of security configuration involves the steps to follow after a message is received to check the content and perform steps like replay detection, freshness detection, signature checking, evaluation of client certificate authentication for server to server communication, etc. This is also where profiles that require authentication of the request, such as Attribute Queries, enforce that requirement.

Internally, these rules are run as part of something called the inboundInterceptorFlows collection, which is a list of "interceptor" webflows to run before accepting a request for further processing. While this is in principle an extensible feature, in most cases you don't need to even think about this mechanism, and it's configured for you for all the built-in profile beans to do the "right" thing, provided you inherit any custom profile beans you want to use for overrides from the built-in beans listed in the RelyingPartyConfiguration (e.g., "Shibboleth.SSO", "SAML2.AttributeQuery").

Normally you need never customize these flows directly, other than via a few properties defined for that purpose, such as idp.policy.messageLifetime.

These beans are typically defined internally in various system files for use, or are defined in conf/credentials.xml or conf/relying-party.xml:

The following beans may be defined in conf/global.xml and are, as a result, not reloadable. These lists override library defaults globally and allow updates to these policies in the event of an algorithm compromise or other local constraints.