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/ecp | SAML2.ECP | Session Initiator flow for SAML 2 ECP 2.0 profile |
sp/initiator/saml2 | SAML2.SSO | Session Initiator flow for SAML 2 Browser SSO profile |
sp/consumer/saml2/ecp | SAML2.ECP | Token Consumer flow for SAML 2 ECP 2.0 profile via PAOS |
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 |
sp/logout/consumer/saml2/redirect | SAML2.Logout | Logout Consumer flow for SAML 2 Browser Single Logout profile via HTTP-Redirect |
sp/logout/consumer/saml2/post | SAML2.Logout | Logout Consumer flow for SAML 2 Browser Single Logout profile via HTTP-POST |
sp/logout/consumer/saml2/post-simplesign | SAML2.Logout | Logout Consumer flow for SAML 2 Browser Single Logout profile via HTTP-POST-SimpleSign |
sp/logout/consumer/saml2/artifact | SAML2.Logout | Logout Consumer flow for SAML 2 Browser Single Logout profile via HTTP-Artifact |
Customizing Flow Order
By default, all plugins will register their supported 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 and Logout Consumers is the order shown above in the table. While unlikely to be necessary, configuring or limiting this on an Agent/Application bean is supported via (e.g.,) 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' }}" />(Similarly for logout via the logoutConsumers property.)
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.
When using the file system, the Hub predefines a set of properties to specify the locations of the files used by default, which are located under credentials/sp in the IdP/Hub configuration tree (the location is up to you if you want to move them, but was chosen to avoid any possible confusion with keys used for IdP behavior.
The “out of the box” install supports only a single set of keypairs for use globally by all Agents for simplicity.
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/saml-default-signing.key
sp.saml.signing.cert = %{idp.home}/credentials/sp/saml-default-signing.crt
sp.saml.encryption.key = %{idp.home}/credentials/sp/saml-default-encryption.key
sp.saml.encryption.cert = %{idp.home}/credentials/sp/saml-default-encryption.crtThe paths are of course entirely arbitrary, but using these properties will allow the system to automatically “equip” those keys and certificates by default without messing with additional files or editing any XML.
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.
The Hub supports a more complex mechanism for specifying credentials based on various criteria to support exception-driven selection, segregating keys by Agent or RelyingParty, or just generally a whole lot of advanced cases. This is discussed for SAML in the TBD topic.
SAML Security Configurations
As in the IdP, there are a number of properties provided, referencing built-in beans, 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 as that is basically a historical feature now).
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.)
Note that while the IdP currently relies on some of these configuration objects to determine which keys to use, the Hub has been developed to use that mechanism only as a fallback, and instead resolves keys to use at runtime with a new CredentialResolver service, discussed separately.
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 (the default), requires the presence of the SubjectConfirmation’s |
sp.saml.requireNotOnOrAfter | If true (the default), requires the presence of the SubjectConfirmation’s |
sp.saml.allowUnsolicited | If true (the default), accepts Assertions delivered with no |
sp.saml.checkAddress | If true (the default), requires a match between the client’s address and the SubjectConfirmation’s |
sp.saml.checkInResponseTo | If true (the default), requires the |
sp.saml.checkReplay | If true (the default), enables message and assertion replay checks based on 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 ECP Profile 2.0 |
| ||
SAML 2.0 Browser Single Logout |
|