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.SSO
The SAML 2.0 Browser SSO profile (the one people typically think of as being “SAML”) is represented by the SAML2.SSO bean and implements the net.shibboleth.sp.saml.saml2.profile.config.BrowserSSOProfileConfiguration 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/sso/browser
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.SSO.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.SSO" p:assertionLifetime="PT1M" />
<!-- 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.SSO" p:assertionLifetime="PT1M" />
<!-- 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.SSO" p:assertionLifetime="PT1M" />
<!-- 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 |
There are a number of bitmask constants defined that regulate what SAML options an Agent is permitted to send to the Hub to override behavior, whether defaulted or explicit, when making SAML requests. By default, Agents are given permission to control these options (mostly for legacy compatibility reasons). Most commonly, if you were to set such an option within the Hub explicitly, you would tend to also want to restrict the ability for Agents to override it.
Options controllable include these beans that supply the relevant bit constant:
SAML2.SSO.FEATURE_AUTHNCONTEXT
SAML2.SSO.FEATURE_FORCEAUTHN
SAML2.SSO.FEATURE_NAMEIDFORMAT
SAML2.SSO.FEATURE_SPNAMEQUALIFIER
Of these, the first is probably the most significant/common to want to block to prevent any override of authentication policy managed upstream of the Agent, possibly at an IdP.
Note that while the underlying setting is an Integer, the setter relies on a Set<Integer> as input in order to simplify the Spring wiring needed to combine flags.
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
signRequests
Type Boolean | Default false | 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 false, as signing <AuthnRequest> messages is rarely useful absent other settings to reject unsolicited responses and enforce message correlation. In the vast majority of cases, it is more effective to enforce the results of a request than to assume the content of a request was communicated properly, as well as being much more efficient.
signResponses
Type Boolean | Default false | 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.
This setting is ignored for this profile, as there are no responses issued by the SP to the IdP.
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 is ignored for this profile, as there are no requests issued by the IdP to the SP.
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 false | Interface | Dynamic encryptNameIDsPredicate |
Controls whether a <NameID> element present in an <AuthnRequest> message will be encrypted.
It is very rare to include such an element in a request, and the Hub provides no built-in support for this, but through customization one could be added and this setting determines whether to attempt to encrypt it in the name of privacy.
Note that such an element is NOT a hint to the IdP about the identity of a user, but a mandatory signal that the resulting assertion MUST carry a matching <NameID>.
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 response. (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 response. (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.
requireSignedAssertions
Type Boolean | Default false | Interface | Dynamic requireSignedAssertionsPredicate |
Controls whether to require signed SAML Assertions independently of the standard security requirements of the profile. That is, regardless of this setting, Assertions must be signed if the Response is not signed, but this setting applies this requirement even if the Response is signed (which is the best practice).
There is in general no reason to change this setting, as SAML Assertions have long since been replaced by OAuth tokens for use in scenarios in which an independent signature would offer value.
assertionLifetime
Type Duration | Default null | Interface | Dynamic assertionLifetimeLookupStrategy |
Limits the maximum lifetime of any SAML Assertion delivered via this profile. Defaults to null, applying no particular maximum while simply requiring validity at the point the Response is received.
There is in general no reason to change this setting, as SAML Assertions have long since been replaced by OAuth tokens for use in scenarios in which an extended lifetime would offer value, and the important time constraints under this profile are found in the <SubjectConfirmation> area. Replay checking also helps prevent misuse, though if you do have the ability to enforce a specific validity period, it obviously doesn’t hurt to do so. This is quite a bit easier when working with a single IdP of course.
assertionAudiences
Type Set<String> | Default null | Interface | Dynamic assertionAudiencesLookupStrategy |
Supplies additional values to use when validating an incoming SAML Assertion’s <AudienceRestriction>condition. Typically the SP’s own effective entityID is implicitly the only audience value accepted during validation; this setting allows that to be supplemented by addtional values.
This setting is typically used to correct for buggy behavior on the part of an IdP (though this is typically unwise and such bugs would usually signify more serious bugs may be present). It should not be used to correct for mistakes in an SP’s own configuration in determining the proper entityID to self-assign during validation.
resolveAttributes
Type Boolean | Default %{sp.saml.resolveAttributes:false} | Interface | Dynamic resolveAttributesPredicate |
Controls whether the Hub should invoke the Attribute Resolver service built into the IdP software for the purpose of locally resolving additional data for the Agent, or to modify/transform the data extracted from the IdP’s response. This is a powerful, though somewhat complex, capability that allows the Hub to leverage the full range of features in the Attribute Resolver service, which allow connections to databases, LDAP directories, web services, and other SAML Attribute Authorities.
This setting is defaulted globally via the sp.saml.resolveAttributes Java property, and defaults to false.
There may be other settings necessary for this feature to work properly (TBD).
requestedIdPAttributeNames
Type Collection<String> | Default null | Interface | Dynamic requestedIdPAttributeNamesLookupStrategy |
Provides a collection of IdPAttribute names to resolve if invoking the Attribute Resolver service (via resolveAttributes being true).
By default, the resolver will attempt to resolve all defined Attribute Definitions; this setting constrains the resolution process to a specific set.
attributeRecipientGroupID
Type String | Default null | Interface | Dynamic attributeRecipientGroupIDLookupStrategy |
Both SAML and OpenID have a concept of a “group” of relying parties that are linked together for the purposes of generating pairwise ID values that would ordinarily be targeted at a single relying party. SAML refers to this as an “Affiliation” while OpenID calls it a “sector_id”.
This setting provides such a value (it is typically in the form of a URI) to the Attribute Resolver service (if resolveAttributes is true). It is not typically needed by a Hub, as pairwise identifiers are typically something an IdP would produce.
attributeIndex
Type String | Default null | Interface | Dynamic attributeIndexLookupStrategy |
Controls the value of the AttributeConsumingServiceIndex XML Attribute in a SAML <AuthnRequest> message issued by the Hub. This a mechanism for referencing an entry in an SP’s SAML Metadata describing what SAML Attributes may be requested or required. It is rarely used due to the difficulty in articulating attribute requirements in the face of so much non-standardization in the naming of SAML Attributes.
Agents can override this value in their request to the Hub.
authnContextComparison
Type String | Default null | Interface | Dynamic authnContextComparisonLookupStrategy |
Controls the value of the Comparison XML Attribute in the <RequestedAuthnContext> XML Element in a SAML <AuthnRequest> message issued by the Hub. This allows use of alternative comparison operators instead of the default (“exact”). This is not commonly used as most IdPs either do not support the other defined values or are not configured to handle them.
Agents (if permitted by other settings) can override this value in their request to the Hub.
maximumTimeSinceAuthn
Type Duration | Default %{sp.saml.maxTimeSinceAuthn:0} | Interface | Dynamic maximumTimeSinceAuthnLookupStrategy |
Limits the amount of time elapsed between the delivery of a SAML Assertion and the AuthnInstant XML Attribute inside the Assertion for the Assertion to be accepted as valid. If this value is exceeded or the XML Attribute is absent, the Assertion is not accepted and an error is usually the result (unless an additional valid Assertion were present).
A zero or null value indicates no limit. This setting is defaulted globally via the sp.saml.maxTimeSinceAuthn Java property, and defaults to zero.
Agents may have similar capabilities, but this is enforced at the Hub layer.
proxyCount
Type Integer | Default null | Interface | Dynamic proxyCountLookupStrategy |
Controls the value of the ProxyCount XML Attribute in the <Scoping> XML Element in a SAML <AuthnRequest> message issued by the Hub. The Element is included only if this setting is non-null.
Most IdPs do not support this setting, and some may break if the Element itself is present, so use with caution.
requestedAttributes
Type Collection<RequestedAttribute> | Default null | Interface | Dynamic requestedAttributesLookupStrategy |
Allows use of a SAML extension for supplying <RequestedAttribute> XML Elements (from the SAML Metadata schema) in an extension in a SAML <AuthnRequest> message issued by the Hub.
Few IdPs support this extension outside of Shibboleth, and the request is advisory so the processing is at the IdP’s discretion.
Actually supplying this setting is not straighttforward in Spring’s XML syntax, and the usual means of doing so would be via Function using the requestedAttributesLookupStrategy variant to allow for construction of the relevant objects.
sPNameQualifier
Type String | Default null | Interface | Dynamic sPNameQualifierLookupStrategy |
Related to the use case for the attributeRecipientGroupID setting, this controls the value of the SPNameQualifier XML Attribute in the <NameIDPolicy> XML Element in a SAML <AuthnRequest> message issued by the Hub.
Not commonly used, this allows an SP to explicitly indicate an Affiliation value an IdP should use in computing a SAML “persistent” <NameID>. It may have applicability in other rare cases, but is generally only relevant in that scenario. It is unlikely to be supported or even noticed by most IdPs other than Shibboleth.
Agents (if permitted by other settings) can override this value in their request to the Hub.
checkAddress
Type Boolean | Default %{sp.saml.checkAddress:true} | Interface | Dynamic checkAddressPredicate |
Controls whether to compare the client’s IP Address directly with the value of the Address XML Attribute in a SAML Assertion during validation, rejecting any Assertion that does not contain a matching value.
The default value of this setting is controlled by the global property sp.saml.checkAddress, which is true by default.
This is frequently impossible to require in this age of broken networks that have destroyed the Internet’s fundamental end-to-end principle. While not a critical security check in comparison with others, the use of bearer tokens is subject to many threats and every bit helps, so the setting remains on by default.
checkInResponseTo
Type Boolean | Default %{sp.saml.checkInResponseTo:true} | Interface | Dynamic checkInResponseToPredicate |
Controls whether SAML Responses' and Assertions' an InResponseTo XML Attribute, if set, must match a value recorded by the Hub while issuing a corresponding request to ensure message correlation is enforced. The original request identifier is tracked in an implementation-specific fashion and retrieved when processing an incoming message.
The default value of this setting is controlled by the global property sp.saml.checkInResponseTo, which is true by default.
Disabling this check is typically needed for broken IdPs or in cases in which there are problems getting the message ID retrieval step to function properly. If requests are not signed, as they typically are not, this check is usually only relevant as a means of preventing unsolicited responses if the option to allow them is disabled.
forceAuthn
Type Boolean | Default false | Interface | Dynamic forceAuthnPredicate |
Controls whether to set the ForceAuthn XML Attribute to true in a SAML <AuthnRequest> message issued by the Hub. The default is false.
Enabling this should be done with caution because some IdPs will not respond properly to this setting, or fail outright, and using it creates substantial inconvenience for users. The web is an inherently insecure platform built on bearer tokens (i.e., cookies). Applying such a requirement achieves little benefit at a substantial cost to user convenience, and is actually incompatible with a variety of strong authentication methods that do not support user presence verification.
Agents (if permitted by other settings) can override this value in their request to the Hub.
allowUnsolicited
Type Boolean | Default %{sp.saml.allowUnsolicited:true} | Interface | Dynamic allowUnsolicitedPredicate |
Controls whether to accept SAML Responses and Assertions that carry no InResponseTo XML Attribute, indicating they are issued by an IdP on its own rather than in response to a request from the SP. While this is a required feature of SAML IdPs/SPs, it is essentially a XSRF attack by definition and may be blocked by means of this setting, provided the checkInResponseTo setting also remains enabled.