Versions Compared

Key

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

...

Expand
titleSigning and Encryption

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
Code Block
languagexml
<!-- 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
Code Block
languagexml
<!-- 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
Code Block
languagexml
<!-- 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
Code Block
languagexml
<!-- 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
Code Block
languagexml
<!-- 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.

...

Expand
titleProperties

Properties defined in idp.properties directly related to this configuration area follow:

Property / Type / Default

Default

Function

idp.cookie.secure

Boolean

false

If true, all cookies issued by the IdP (not including the container) will be limited to TLS

idp.cookie.httpOnly

Boolean

true

If true, all cookies issued by the IdP (not including the container) will contain the HttpOnly property

idp.cookie.domain

String

Overrides the domain of any cookies issued by the IdP, not including the container

idp.cookie.path

String

Overrides the path of any cookies issued by the IdP, not including the container

idp.cookie.maxAge

Integer

31536000 (1 year)

Lifetime in seconds of cookies issued by the IdP that are meant to span sessions (365 days)

idp.cookie.sameSite

"Null", "None", "Lax", or "Strict"

"None"

Default SameSite value to apply to cookies via servlet filter if no explicit rule for the named cookie is specified

idp.cookie.sameSiteCondition

Bean ID of Predicate<ServletRequest>

shibboleth.Conditions.FALSE

Predicate<ServletRequest> condition bean controlling whether SameSite filter runs

idp.sealer.keyStrategy

Bean ID of DataSealerKeyStrategy

shibboleth.DataSealerKeyStrategy

Bean ID supporting the DataSealerKeyStrategy interface to use in place of the built-in option.

idp.sealer.storeType

String

"JCEKS"

Type of Java keystore used for IdP's internal AES encryption key

idp.sealer.updateInterval

Duration

PT15M

Time between checks for a new AES key version

idp.sealer.aliasBase

String

"secret"

Case insensitive name of keystore alias prefix used in AES keystore (the entries will be suffixed by the key version number)

idp.sealer.storeResource

Resource path

Keystore resource containing AES encryption key, usually a file path

idp.sealer.versionResource

Resource path

Resource that tracks the "active" AES encryption key version, usually a file path

idp.sealer.storePassword

String

Keystore password unlocking AES encryption keystore, typically set during installation

idp.sealer.keyPassword

String

Key password unlocking AES encryption key, typically set to the same as the previous property and set during installation

idp.signing.key

Resource path

Resource containing private key for signing, typically a file in the credentials directory

idp.signing.cert

Resource path

Resource containing the public key certificate inserted into signed messages, typically a file in the credentials directory

idp.encryption.key

Resource path

Resource containing a private key for decryption, typically a file in the credentials directory

idp.encryption.cert

Resource path

Resource containing a public key certificate given to others needing to encrypt data for the IdP, typically a file in the credentials directory

idp.encryption.key.2

Resource path

Resource containing an alternate private key for decryption, generally unused except while changing decryption keys

idp.encryption.cert.2

Resource path

Resource containing an alternate public key certificate, generally unused except while changing decryption keys

idp.security.config

Bean ID of SecurityConfiguration

shibboleth.DefaultSecurityConfiguration

Name of Spring bean supplying the default SecurityConfiguration

idp.signing.config

Bean ID of SignatureSigningConfiguration

shibboleth.SigningConfiguration.SHA256

Name of Spring bean supplying the default SignatureSigningConfiguration

idp.encryption.config

Bean ID of EncryptionConfiguration

shibboleth.EncryptionConfiguration.CBC

Name of Spring bean supplying the default EncryptionConfiguration

idp.trust.signatures

Bean ID of SignatureTrustEngine

shibboleth.ChainingSignatureTrustEngine

Name of Spring bean for the trust engine used to verify signatures

idp.trust.certificates

Bean ID of TrustEngine

shibboleth.ChainingX509TrustEngine

Name of Spring bean for the trust engine used to verify TLS certificates

idp.encryption.optional

Boolean

false

If true, failure to locate an encryption key to use, when enabled, won't result in request failure

idp.errors.detailed

Boolean

false

If true, more detailed error information may be returned in profile responses, which could leak useful information in rare cases

idp.errors.signed

Boolean

true

When message signing is enabled, controls whether to sign responses that signal errors as opposed to successful outcomes

idp.policy.messageLifetime

Duration

PT3M

Default freshness window for accepting timestamped messages

idp.policy.assertionLifetime

Duration

PT3M

Default freshness window for accepting timestamped assertions

idp.policy.clockSkew

Duration

PT3M

Default allowance for clock differences between systems

idp.artifact.secureChannel

Boolean

true

If true, skips signing/encryption when the message will be passed by reference (via artifact in SAML terms)

idp.security.basicKeyInfoFactory

Bean ID of KeyInfoGeneratorManager

shibboleth.BasicKeyInfoGeneratorFactory

Overrides the BasicKeyInfoGeneratorFactory used by default

idp.security.x509KeyInfoFactory

Bean ID of KeyInfoGeneratorManager

shibboleth.X509KeyInfoGeneratorFactory

Overrides the X509KeyInfoGeneratorFactory used by default

Expand
titleBeans

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

Name

Type

Description

shibboleth.BasicX509CredentialFactoryBean

BasicX509CredentialFactoryBean

Parent bean used for defining an X.509 keypair via external resources (this is the most common way)

shibboleth.X509InlineCredentialFactoryBean

X509InlineCredentialFactoryBean

Parent bean used for defining an X.509 credential via inline data

shibboleth.BasicResourceCredentialFactoryBean

BasicResourceCredentialFactoryBean

Parent bean used for defining a basic public/private or secret credential via external resources

shibboleth.BasicInlineCredentialFactoryBean

BasicInlineCredentialFactoryBean

Parent bean used for defining a basic public/private or secret credential via inline data

shibboleth.DefaultSigningCredential

Credential 

Keypair used for signing, usually including a certificate

shibboleth.DefaultClientTLSCredential

Credential

Keypair used for client TLS, including a certificate

shibboleth.DefaultEncryptionCredentials

List<Credential>

Collection of keypairs used to decrypt data sent by others (technically only the private key matters here)

shibboleth.DefaultSecurityConfiguration

SecurityConfiguration

Default security configuration used by all profile beans

shibboleth.SecurityConfiguration.SHA256

SecurityConfiguration

Security configuration that directly incorporates the SHA-256 signing configuration

shibboleth.SecurityConfiguration.SHA1

SecurityConfiguration

Security configuration that directly incorporates the SHA-1 signing configuration

shibboleth.SecurityConfiguration.CBC

SecurityConfiguration

Security configuration that directly incorporates the AES-CBC encryption configuration

shibboleth.SecurityConfiguration.GCM

SecurityConfiguration

Security configuration that directly incorporates the AES-GCM encryption configuration

shibboleth.SigningConfiguration.SHA256

BasicSignatureSigningConfiguration

Signing configuration that uses the SHA-256 digest algorithm

shibboleth.SigningConfiguration.SHA1

BasicSignatureSigningConfiguration

Signing configuration that uses the SHA-1 digest algorithm

shibboleth.EncryptionConfiguration.CBC

EncryptionConfiguration

Encryption configuration that uses the AES-CBC encryption algorithm

shibboleth.EncryptionConfiguration.GCM

EncryptionConfiguration

Encryption configuration that uses the AES-GCM encryption algorithm

shibboleth.ExplicitKeySignatureTrustEngine

ExplicitKeySignatureTrustEngine

Signature verifier that relies on explicit keys in metadata

shibboleth.PKIXSignatureTrustEngine

PKIXSignatureTrustEngine

Signature verifier that validates certificates against PKIX rules in metadata

shibboleth.ChainingSignatureTrustEngine

ChainingSignatureTrustEngine

Signature verifier that chains the previous two beans together

shibboleth.ExplicitKeyX509TrustEngine

ExplicitKeyTrustEngine

Client certificate verifier that relies on explicit keys in metadata

shibboleth.PKIXX509TrustEngine

PKIXX509CredentialTrustEngine

Client certificate verifier that validates certificates against PKIX rules in metadata

shibboleth.ChainingX509TrustEngine

ChainingTrustEngine

Client certificate verifier that chains the previous two beans together

shibboleth.SameSiteCookieMap

Map<String,SameSiteValue>

Map of rules for assigning explicit SameSite values to specific cookies via servlet filter

shibboleth.BasicKeyInfoGeneratorFactory

BasicKeyInfoGeneratorFactory

Parent bean for defining custom KeyInfo behavior for non-certificate credentials

shibboleth.X509KeyInfoGeneratorFactory

X509KeyInfoGeneratorFactory

Parent bean for defining custom KeyInfo behavior for X.500 certificates

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.

Name

Type

Description

shibboleth.IncludedSignatureAlgorithms

Set<String>

Explicitly names signature and digest algorithms to allow, with others disallowed

shibboleth.ExcludedSignatureAlgorithms

Set<String>

Explicitly names signature and digest algorithms to block, with others allowed

shibboleth.IncludedEncryptionAlgorithms

Set<String>

Explicitly names encryption algorithms to allow, with others disallowed

shibboleth.ExcludedEncryptionAlgorithms

Set<String>

Explicitly names encryption algorithms to block, with others allowed

...