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 |
|---|---|---|---|
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. | |
authnContextComparison | one of: | "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. |
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). | |
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). | |
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"
.