This software is not yet released and this is preliminary documentaton subject to significant change. It should not be used in production or to protect important resources at this stage.
ProfileConfiguration-SAML2.Logout
The SAML 2.0 Browser Single Logout profile is represented by the SAML2.Logout bean and implements the net.shibboleth.sp.saml.saml2.profile.config.SingleLogoutProfileConfiguration interface. It is layered on a number of base interfaces that are common to various SAML profiles.
Metadata-Driven Usage
The beans and wiring for this are not yet present in the under-development plugins, but will be added prior to the final release.
For MetadataDrivenConfigurationof this profile, tags may either contain the generic prefix http://shibboleth.net/ns/profilesor the profile specific prefix of http://shibboleth.net/ns/profiles/saml2/logout
To trigger/support metadata globally for all profiles, the property sp.service.agents.useMetadataDrivenProfiles may be set to true. To enable it on a more fine-grained basis, the modified bean ID SAML2.Logout.MDDriven may be used via reference or as a parent to install it into a particular context.
Note that individual settings applied to a bean derived from it will override any Metadata tags that may be present for that setting.
Example Usage
In the event that you decide to override a setting that cannot be handled with a Java property noted in the SAMLSettingsReference, you may do this like so (in conf/sp/agents.xml). The example is not one that is likely to come up but demonstrates use of a setting for illustration purposes.
To override globally, uncomment the default bean near the end of the file:
<util:list id="shibboleth.sp.DefaultProfileConfigurations">
<bean parent="SAML2.Logout" p:asynchronous="false" />
<!-- Any other active default profiles must be declared here as well. -->
</util:list>To override the setting for a particular IdP (though using SAML Metadata is preferred, see above):
<util:list id="shibboleth.sp.RelyingPartyOverrides">
<bean p:id="Guests" parent="RelyingPartyByName" c:candidates="https://guest.example.org/idp">
<property name="profileConfigurations">
<bean parent="SAML2.Logout" p:asynchronous="false" />
<!-- Any other active default profiles must be declared here as well. -->
</property>
</bean>
</util:list>Finally, one may do so for a specific Agent via the profileConfigurations bean property:
<bean p:id="hr.example.org" parent="shibboleth.sp.Agent">
<property name="profileConfigurations">
<bean parent="SAML2.Logout" p:asynchronous="false" />
<!-- Any other active default profiles must be declared here as well. -->
</property>
</bean>Settings Reference
This is a complete reference to the supported settings available for this profile. Where applicable, any global properties that may be used to control the default value are noted. The settings are grouped by the Java interface providing them, which is also noted for reference.
Most Boolean-valued settings may be derived dynamically by installing a companion setting of type Predicate<ProfileRequestContext>. Similarly, most other settings of different type <T> may be derived dynamically by installing a companion setting of type Function<ProfileRequestContext,T>. The names of these companion settings are noted below when they exist. The IdP also includes many PredefinedBeans that provide scripted or Spring Expression versions of those interfaces.
activationCondition
Type | Default | Interface | Dynamic No |
Attaches a condition to the profile that must evaluate to true at runtime before the profile will be allowed to run. Typically this is unused, but provides an alternative “axis” of control for determining which profiles may be active for a request.
disallowedFeatures
Type Set<Integer> | Default | Interface | Dynamic disallowedFeaturesLookupStrategy |
While this setting exists, there are no feature flags defined for this profile.
securityConfiguration
Type | Default %{sp.saml.security.config} | Interface | Dynamic securityConfigurationLookupStrategy |
Controls the security configuration used to supply keys, certificates, clock skew, identifier generation, and XML Security algorithm defaults and rules governing signing, validation, encryption, decryption, and TLS connection handling.
Typically this does not require modification except globally through the use of various properties, but in more advanced cases, it is possible to directly control the entire set of configuration objects. The properties and beans provided for “intermediate” levels of control are documented in the SAMLSettingsReference parent topic.
The default bean used is set via the sp.saml.security.config Java property and defaults to the bean named shibboleth.sp.DefaultXMLSecurityConfiguration (this is internally declared).
These alternate beans may be set either via that property or on a more fine-grained basis to toggle two common security algorithm defaults (SHA-256 to/from SHA-1 or AES-CBC to/from AES-GCM):
shibboleth.sp.SecurityConfiguration.SHA256
shibboleth.sp.SecurityConfiguration.SHA1
shibboleth.sp.SecurityConfiguration.CBC
shibboleth.sp.SecurityConfiguration.GCM
Note that these settings control the act of “creation” of a signed or encrypted object. While there are ways to actually turn off support for particular algorithms, you need not (as an SP) use these settings to allow the use of, for example, AES-GCM. The SP simply supports this algorithm automatically for decryption purposes if an IdP uses it.
signRequests
Type Boolean | Default true | Interface | Dynamic signRequestsPredicate |
Enables the creation of a binding-specific signature over requests issued to an IdP. The format of a signature depends on the SAML binding in use.
Defaults to a built-in condition object that evaluates the properties of the channel over which the request will be sent. Because the SP only supports front-channel logout, that condition always evaluates to “true”.
signResponses
Type Boolean | Default true | Interface | Dynamic signResponsesPredicate |
Enables the creation of a binding-specific signature over responses issued to an IdP. The format of a signature depends on the SAML binding in use.
Defaults to a built-in condition object that evaluates the properties of the channel over which the request will be sent. Because the SP only supports front-channel logout, that condition always evaluates to “true”.
messageHandler
Type | Default | Interface | Dynamic messageHandlerLookupStrategy |
Low-level feature allowing installation of a Java Function that may examine or even alter an inbound or outbound SAML message. The hook for this feature runs after signature validation inbound and before signature creation outbound, so that it may be used without contaminating those steps.
A MessageContext is a specialized context that exists as a half-duplex representation of a message exchange and provides access to a message object and other subcontexts as may be used during processing. A ProfileRequestContext may contain either or both inbound or outbound MessageContext objects, though the SP use cases typically result in only one or the other being present.
The Function may return null as an indication of success, or an Exception object in order to raise an error and prevent further processing.
ignoreRequestSignatures
Type Boolean | Default false | Interface | Dynamic ignoreRequestSignaturesPredicate |
This setting causes the Hub to ignore any signatures it finds on logout messages from an IdP. It will not evaluate them, but there are other settings that control whether the lack of a valid signature will actually cause a subsequent error or not.
This is used to work around broken IdPs whose signatures are invalid or who use signing keys that are not accessible via trustable SAML Metadata.
encryptionOptional
Type Boolean | Default %{sp.saml.encryption.optional:true} | Interface | Dynamic encryptionOptionalPredicate |
Controls the behavior when preparing messages that require XML Encryption (due to other settings/defaults) in cases where no encryption key can be identified to use from the IdP’s SAML Metadata. If this setting is false, then the absence of a key when encryption is determined to be necessary results in an error.
This setting is defaulted globally via the sp.saml.encryption.optional Java property, and defaults to true because the use of encryption from the SP tends to be of relatively minimal importance.
Encryption is very rare in <AuthnRequest> messages and is only triggered when unusual, custom message content is present.
encryptNameIDs
Type Boolean | Default true (*) | Interface | Dynamic encryptNameIDsPredicate |
Controls whether a <NameID> element present in a <LogoutRequest> message will be encrypted.
Defaults to a built-in condition object that evaluates the properties of the channel over which the request will be sent. Because the SP only supports front-channel logout, that condition always evaluates to “true”, but the default condition also determines whether to encrypt based on the Format XML Attribute of the <NameID>and will bypass encryption for any values for which it is configured to do so.
The default set that do not result in encryption is the single value “urn:oasis:names:tc:SAML:2.0:nameid-format:entity”; you may define a Set bean named shibboleth.PlaintextNameIDFormats to enumerate other values to leave in plaintext if desired.
signArtifactRequests
Type Boolean | Default see below | Interface | Dynamic signArtifactRequestsPredicate |
Controls whether to sign SOAP requests used to dereference SAML Artifacts when the HTTP-Artifact binding is used by an IdP to deliver a logout message. (The SP never issues its own Artifacts as this binding is no longer supported for its requests.)
The default setting depends on the scheme and port used by the IdP’s Artifact resolution endpoint. The setting defaults to true if HTTP, or HTTPS over port 443, are used. Otherwise it defaults to false. This automatically enables signing when it is expected to be necessary and disables it otherwise.
clientTLSArtifactRequests
Type Boolean | Default see below | Interface | Dynamic clientTLSArtifactRequestsPredicate |
Controls whether to use Client TLS during SOAP requests used to dereference SAML Artifacts when the HTTP-Artifact binding is used by an IdP to deliver a logout message. (The SP never issues its own Artifacts as this binding is no longer supported for its requests.)
The default setting depends on the scheme and port used by the IdP’s Artifact resolution endpoint. The setting defaults to false if HTTP, or HTTPS over port 443, are used. Otherwise it defaults to true. This automatically enables Client TLS when it is expected to be possible and necessary and disables it otherwise.
asynchronous
Type Boolean | Default true | Interface | Dynamic asynchronousPredicate |
Controls insertion of the “Asynchronous” extension into the logout requests issued by the Hub. This extension explicitly signals that the IdP need not respond to the SP with a <LogoutResponse> message, as this is typically superfluous to the SP, which cannot act on the result in any event.
While it should be ignored by any IdP that cannot process the extension, it can be disabled if necessary.
qualifiedNameIDFormats
Type Collection<String> | Default
| Interface | Dynamic qualifiedNameIDFormatsLookupStrategy |
The matching process defined by SAML for logout requires awareness of how the NameQualifier and SPNameQualifier XML attributes are defined for specific identifier formats. The core standard only defines expected behavior for these attributes in the case of the transient or persistent formats defined by the standard. This allows the qualifier values to be “defaulted” based on the identities of the IdP and SP in a logout exchange.
This setting defines to the SP whether any additional formats should be handled this way. For any other formats, the qualifiers must match exactly in order to “match”.