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.

See also SAML2 Sessions Configurations 

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"
.