SSO

The <SSO> element is used to enable and configure support for Single Sign-On/Authentication protocols within the SP. This is of course the primary function of the software, so it is generally present within the <Sessions> element to enable and control SSO settings.

For each protocol activated in the <SSO> element, the order of the Bindings is controlled in protocols.xml.

The use of the <SSO> element results in a basic chain of initiator plugins installed at the recommended "/Login" handler location. For advanced scenarios that require additional plugins or options, additional explicit <SessionInitiator> elements can be added to the end of the surrounding <Sessions> element, but you should never install those handlers to the same default location as the one used by this element. To prevent unforeseen interactions, you likely should remove the shorthand element entirely.

Attributes

Name	Type	Default	Description

Name	Type	Default	Description
entityID	URI		If set, establishes an assumed IdP to use for authentication, if none is passed explicitly with a query string parameter or overridden via content settings.
discoveryProtocol	string		Protocol to use for the Discovery Service. Typically either "SAMLDS" (SAML Discovery Service protocol) or "WAYF" (legacy Shibboleth WAYF protocol).
discoveryURL	URL		Location of the discovery service, e.g., https://ds.example.org/DS
relayState	string		Overrides relayState setting from the <Sessions> element.
entityIDParam	string		Optional, advanced setting for overriding the name of the query string parameter used to override the IdP to use. Normally "entityID" and "providerId" are the parameter names supported. This is provided for supporting unusual application requirements.
target	URL		Allows the resources to return to after SSO to be "locked" to a specific value, even when running as a result of active protection of other resources. In other words, this value overrides the actual resource location when SSO redirection is automatic, including initial access and after a timeout.
The following attribute can be specified for SAML1 and SAML2 protocols:
Name	Type	Default	Description
isPassive	boolean	false	If true, causes the <samlp:AuthnRequest>'s IsPassive attribute to be "true". Can be overridden by content setting or query string parameter.
The following attributes can be specified for the SAML2 protocols:
Name	Type	Default	Description
template	local pathname		An HTML template used during transmission of the <samlp:AuthnRequest> message
outgoingBindings	space delimited URIs		List of SAML binding identifiers that determines the order of preferred <md:SingleSignOnService> bindings to use for the request. If this setting is used, failing to list a binding will prevent the use of an IdP that only supports the omitted binding
acsByIndex	boolean	false	If true, the location of the assertion consumer service to return the assertion to is passed by reference (using an index), rather than passing an explicit URL and binding. Because of the difficulty of ensuring consistent indexing between local configuration and metadata, this is not an advisable feature.
postArtifact	boolean	false	If true, the SAML artifact binding is implemented using a form POST rather then a redirect.
forceAuthn	boolean	false	If true, causes the <samlp:AuthnRequest>'s ForceAuthn attribute to be "true". Can be overridden by content setting or query string parameter. This asks for forced reauthentication by the IdP (bypassing SSO).
authnContextClassRef	space delimited URIs		If set, inserts a <samlp:RequestedAuthnContext> element containing the class reference into the <samlp:AuthnRequest>. This can be a whitespace-delimited list of classes to request. Can be overridden by content setting or query string parameter. This can also be configured on a per-IdP basis via a RelyingParty setting (only applies if a more general value is not supplied).
authnContextComparison	one of: "exact" "minimum" "maximum" "better"	"exact"	If set, inserts a <samlp:RequestedAuthnContext> element containing the comparison operator into the <samlp:AuthnRequest>. Can be overridden by content setting or query string parameter. Ignored unless an authnContextClassRef value is set. This can also be configured on a per-IdP basis via a RelyingParty setting (only applies if a more general value is not supplied)
ECP	boolean	false	If set, enables Enhanced Client/Proxy profile support, causing the SP to recognize the headers sent by an ECP-enabled client and respond with an ECP request instead of a redirect. Note that when this occurs, the IdP need not be known for a request to be generated, unlike in the normal case
requestDelegation	boolean	false	If set, causes the request to carry a <saml:Conditions> element that includes a <saml:AudienceRestriction> identifying the IdP as a desired relying party for the resulting assertion. This convention is associated with support for delegation, in which the SP can authenticate itself with the assertion as the user in the course of subsequent requests to the IdP.
NameIDFormat	URI		If set, causes the request to require the IdP to respond with a NameID identifier of the given format. If the IdP can not fulfill this requirement, it will return an error response (if correctly implemented). This can also be configured on a per-IdP basis via a RelyingParty setting (only applies if a more general value is not supplied).
SPNameQualifier	URI		If set, causes the authentication request to carry a saml:NameIDPolicy with an SPNameQualifier containing the provided value. If the receiving IdP can not fulfill this requirement, it will return an error response (if correctly implemented). This can also be configured on a per-IdP basis via a RelyingParty setting (only applies if a more general value is not supplied).
signing			Controls outbound signing of XML messages. See Signing & Encryption
encryption			Controls outbound encryption of XML messages and content. See Signing & Encryption.
externalInput	boolean	true

Element Content

The content of the element is a whitespace-delimited list of "protocol" identifiers. Protocol identifiers are listed in preferential order, with the most preferred first. The three listed below are built-in to the SP.

SAML2

SAML 2.0 Browser SSO profile.

As a protocol handler, an entityID must be specified/known, which is then used to check for metadata with an <md:IDPSSODescriptor> role supporting SAML 2.0. The absence of either causes a warning to be logged and the handler otherwise ignores the request.

SAML1

SAML 1.x Browser-POST and Browser-Artifact profiles.

As a protocol handler, an entityID must be specified/known, which is then used to check for metadata with an <md:IDPSSODescriptor> role supporting Shibboleth 1.x. The absence of either causes a warning to be logged and the handler otherwise ignores the request.

A "supporting" IdP's role element has a protocolSupportEnumeration attribute containing the value "urn:mace:shibboleth:1.0", with an accompanying <md:SingleSignOnService> with a Binding of "urn:mace:shibboleth:1.0:profiles:AuthnRequest".

ADFS

WS-Federation Passive Interoperability Profile (legacy ADFS) .

The ADFS handler is only available if the adsfs.so extension library is loaded by the SP.

As a protocol handler, an entityID must be specified/known, which is then used to check for metadata with an <md:IDPSSODescriptor> role supporting ADFS. The absence of either causes a warning to be logged and the handler otherwise ignores the request.

A "supporting" IdP's role element has a protocolSupportEnumeration attribute containing the value "http://schemas.xmlsoap.org/ws/2003/07/secext", with an accompanying <md:SingleSignOnService>with a Binding of "http://schemas.xmlsoap.org/ws/2003/07/secext".

Examples

A basic example using a single, fixed IdP, supporting the usual common SAML protocols:

<SSO entityID="https://idp.example.org/idp/shibboleth">
  SAML2 SAML1
</SSO>

An example using a SAML Discovery Service and supporting ECP:

<SSO discoveryProtocol="SAMLDS" ECP="true" discoveryURL="https://examplefederation.org/DS">
  SAML2 SAML1
</SSO>

For a legacy Shibboleth WAYF Service, just replace the discoveryProtocol value with "WAYF"
.

Service Provider 3

SSO