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.
SAMLSettingsReference
Location: conf/sp/agents.xml, conf/sp/saml.properties
The SAML protocol plugin (“net.shibboleth.sp.shibd.saml”) provides SAML protocol support to the Hub. This is a full reference (with subtopics) to all the supplied features and how they may be referenced in the Hub configuration.
Most/all of these settings involve the various objects discussed in the AgentResolverServicedocumentation, with various global defaults established by properties in conf/sp/saml.properties.
The plugin contributes Session Initiator and Token Consumer web flows plus supplemental web flows for other features and profiles, and SAMLProfileConfigurations for all the supported profiles implemented by them.
Web Flows
The following flows are provided.
Flow ID | Profile Config Bean | Description |
|---|---|---|
sp/initiator/saml2 | SAML2.SSO | Session Initiator flow for SAML 2 Browser SSO profile |
sp/consumer/saml2/post | SAML2.SSO | Token Consumer flow for SAML 2 Browser SSO profile via HTTP-POST |
sp/consumer/saml2/post-simplesign | SAML2.SSO | Token Consumer flow for SAML 2 Browser SSO profile via HTTP-POST-SimpleSign |
sp/consumer/saml2/artifact | SAML2.SSO | Token Consumer flow for SAML 2 Browser SSO profile via HTTP-Artifact |
sp/logout/initiator/saml2 | SAML2.Logout | Logout Initiator flow for SAML 2 Browser Single Logout profile |
Note: Rest of Single Logout and ECP are TBD
Customizing Flow Order
By default, all plugins will register their supported Session Initiator and Token Consumer flows in an internally-defined default order. Precedence between plugins is governed by a set of “ordering” properties that are defined by each plugin to control relative order, lower being “earlier”.
The SAML property for this is sp.saml.relativeOrder and defaults to 1.
Within the SAML plugin, the default order of Token Consumers for Browser SSO is the order shown above in the table (post, post-simplesign, artifact). While unlikely to be necessary, configuring or limiting this on an Agent/Application bean is supported via the tokenConsumers setting, and the values are specified after omitting the “sp/consumer/” prefix:
<bean p:id="localhost" parent="shibboleth.sp.Agent" p:tokenConsumers="#{{ 'saml2/post' }}" />Java Properties
The plugin adds conf/sp/saml.properties to the configuration and the following properties are used to make global/default configuration of SAML-enabled Agents easy to accomplish without XML. The properties are collected here into groups based on their general function and type.
Specifying Keys/Certificates
By default the Hub expects private keys and certificates for use with SAML processing to be located on the file system, as the IdP does.
As the IdP does, the Hub supports a number of more advanced mechanisms for loading credentials using more advanced Spring configuration in conf/sp/saml-credentials.xml, but we have never actually documented them.
When using the file system, the Hub predefines a set of properties to specify the locations of the files, which are located by default under credentials/sp in the IdP/Hub configuration tree (the location is up to you, but was chosen to avoid any possible confusion with keys used for IdP behavior since the IdP installation does create those currently by default).
The supplied XML is designed to support only a single set of keys, or perhaps an additional encryption key to support key rotation, but does not default to handling separate keys for each Agent.
The properties all contain the pathname to the relevant file, generally relative to the %{idp.home} property variable:
sp.saml.signing.key = %{idp.home}/credentials/sp/sp-signing.key
sp.saml.signing.cert = %{idp.home}/credentials/sp/sp-signing.crt
sp.saml.encryption.key = %{idp.home}/credentials/sp/sp-encryption.key
sp.saml.encryption.cert = %{idp.home}/credentials/sp/sp-encryption.crt
#sp.saml.encryption.key.2 = %{idp.home}/credentials/sp/sp-encryption-old.key
#sp.saml.encryption.cert.2 = %{idp.home}/credentials/sp/sp-encryption-old.crtAll but the last two are in the configuration by default and if unset will prevent parts of the Hub from initializing. The paths are of course entirely arbitrary.
The last two are commented but are provided as an example (along with commented XML in conf/sp/saml-credentials.xml that demonstrate how one might add a second encryption key to the configuration during a key rollover process.
Do NOT use the same key for signing and encryption in SAML. While this is safe, it’s a bad idea as it greatly complicates the impact of a key compromise or a key rotation event and makes it almost certain that things will break because of your own or others' mishandling of SAML metadata.
A signing key is also generally only needed when supporting SAML logout or consuming SAML Artifacts (which are practically extinct), but configuring one does no harm.
Something notably with these properties is that they’re largely just examples because the file that embeds these properties into the configuration is user-editable so you are ultimately free to use or not use them as desired.
SAML Security Configurations
As in the IdP, there are a number of beans and properties provided to simplify global changes to the XML signing and encryption algorithms used when creating messages for IdPs. The most relevant ones are below.
Some notable differences from the IdP’s current defaults:
The internal and shipping default for trust evaluation in the SP is to solely rely on explicit keys in SAML Metadata. Support for PKIX (via SAML Metadata extensions) requires overriding defaults (but should be unnecessary).
The internal and shipping default for XML Encryption is AES-CBC. This may be switched to AES-GCM prior to the final release, but currently matches the SP V3 default. (Very few IdPs other than Shibboleth support AES-GCM.)
SAML Profile Behavior
A number of properties control SAML profile behavior globally for all Agents/Applications regardless of the IdP used and are the “simplest” way to configure options when suitable. in particular, they are the simplest way to configure a Hub supporting a single Agent, best suited if Dockerizing the Hub, etc.
These properties are all Boolean-valued and default to true. Most (but not all) of them are controllable on a per-RelyingPartyConfiguration basis, and some of them generally involve relaxing required checks to deal with broken IdPs, which is something you should never do lightly.
Name | Description |
|---|---|
sp.saml.encryption.optional | Controls the behavior of the Hub if told to encrypt data for an IdP and no encryption key is available to do so. When true (the default) processing fails. Encryption is typically only applicable to logout requests and is off by default, so this only comes into play if other non-default profile settings are applied. |
sp.saml.requireRecipient | If true, requires the presence of the SubjectConfirmation’s |
sp.saml.requireNotOnOrAfter | If true, requires the presence of the SubjectConfirmation’s |
sp.saml.allowUnsolicited | If true, accepts Assertions delivered with no |
sp.saml.checkAddress | If true, requires a match between the client’s address and the SubjectConfirmation’s |
sp.saml.checkInResponseTo | If true, requires the |
sp.saml.request.NameIDLookupStrategy | Optional bean ID of a Function<ProfileRequestContext,NameID> to produce content to place into Note this is often misused as a “hint” by commercial products, but in SAML has more precise and critical semantics and is not at all the same as OpenID’s “login_hint” |
sp.saml.logout.authenticated | If true (the default), logout request and responses messages from IdPs must be signed to successfully process them. This is a global setting only. |
Attribute Extraction
A number of properties control some “special” extraction of data into IdPAttributes for all Agents/Applications. For the most part, these are involved with providing backward-compatibility with the older SP’s behavior, along with a few new features. All IdPAttributes produced are String-valued unless otherwise noted.
Property / Type | Type | Default | Description |
|---|---|---|---|
sp.saml.acceptUnfilteredAttributes | Boolean | false | Triggers automatic acceptance of any IdPAttribute that was not subject to any Attribute Filter Policy rule of any sort. This is a very strictly interpreted constraint, and even the slightest reference to an IdPAttribute in a policy will exempt it from this setting. |
sp.saml.extractStandardAttributes | Boolean | false | When set, this causes the SAML processing that produces IdPAttributes to produce one or more “special/standard” IdPAttributes from various specially designated sources in order to provide Agents with information that tended to be built-in to the older SP software. |
sp.saml.issuerAttributeId | String | Shib-Identity-Provider | Name of IdPAttribute to populate with the |
sp.saml.authnInstantAttributeId | String | Shib-Authentication-Instant | Name of IdPAttribute to populate with |
sp.saml.authnContextClassRefAttributeId | String | Shib-AuthnContext-Class | Name of IdPAttribute to populate with |
sp.saml.authnContextDeclRefAttributeId | String | Shib-AuthnContext-Decl | Name of IdPAttribute to populate with |
sp.saml.sessionIndexAttributeId | String | Shib-Session-Index | Name of IdPAttribute to populate with |
sp.saml.consentAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.authorityAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.notBeforeAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.notOnOrAfterAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.sessionNotOnOrAfterAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.addressAttributeId | String |
| Name of IdPAttribute to populate with |
sp.saml.dnsNameAttributeId | String |
| Name of IdPAttribute to populate with |
Plugin Order
The last property of note is one that affects the relative order of functionality between the SAML plugin and any other protocol plugins present in the Hub when attempting various operations that may involve one of a number of protocols. Typically the order won’t affect behavior unless a particular request could be handled with more than one protocol, which is not common.
The sp.saml.relativeOrder property provides an ordinal for SAML, defaulting to 1. The lower the value, the higher the priority relative to other plugins. Each plugin will provide such a property to allow the relative order to be overridden.
Profile Configurations
Beans are supplied for each supported SAML Profile Configuration to allow automatic coonfiguration of profiles through default settings or the properties noted above. They may also be used as parent beans when/if it becomes necessary to control other settings that can’t be addressed with simple properties or if settings need to be overridden on a per-RelyingPartyConfiguration basis.
In most cases, particular when SAML is involved, using SAML Metadata “tags” to control per-IdP behavior is strongly preferred to implementing overrides in the configuration whenever possible. Tags may be added directly to locally-curated metadata, or via the EntityAttributesFilter when using a Federation’s metadata.
The following profile configuration beans are provided by the plugin; see the linked topics for complete settings references:
Bean ID(s) | Profile | Profile ID | Javadoc |
|---|---|---|---|
SAML 2.0 Browser SSO Profile |
| ||
SAML 2.0 Browser Single Logout |
| ||
|
|
|
|