SAML2 SessionInitiator

Advanced Configuration

Note, this is an advanced configuration feature. Most deployments can rely on the <SSO> shorthand element.

1 Advanced Configuration
2 Attributes
- 2.1 Common Attributes
- 2.2 Specific Attributes
3 Child Element
4 Query String Parameters
- 4.1 Common Parameters
- 4.2 Specific Parameters
5 Example
- 5.1 Example of an Embedded AuthnRequest Template

Indicated by type="SAML2", this initiator supports SAML 2.0 authentication requests. 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.

Attributes

Common Attributes

Specific Attributes

Name	Type	Default	Description

Name	Type	Default	Description
template	local pathname		An HTML template used during transmission of the <samlp:AuthnRequest> message.
outgoingBindings	space delimited list of URLs		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.
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
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	URI		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. Tis 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)
attributeIndex^3.3	string		If set, populates the AttributeConsumingServiceIndex XML attribute in the request

Child Element

Name	Cardinality		Description

Name	Cardinality		Description
<samlp:AuthnRequest>	0 or 1		If present, the XML is used as a template for the request issued. When the configuration file is validated during initial setup, some of the required (but meaningless) attributes on this element are required. This per-request information, such as IssueInstant and ID, is replaced/reset at runtime. Useful for supplying advanced request content that cannot be configured in a simpler way

Query String Parameters

The following can be provided via the Initiator Protocol

Common Parameters

Specific Parameters

Parameter Name	Parameter Value Type	Default	Description

Parameter Name	Parameter Value Type	Default	Description
forceAuthn	boolean		Establish a value for the ForceAuthn attribute of the <samlp:AuthnRequest>. This asks for forced reauthentication by the IdP (bypassing SSO).
isPassive	boolean		Establish a value for the IsPassive attribute of the <samlp:AuthnRequest> or the IsPassive parameter of the DS redirect
authnContextComparison	One of: exact, minimum, maximum, better	exact	Indicates the required relationship between a requested context class and the resulting form of authentication.
NameIDFormat	URI		If set, causes the authentication request to carry a saml:NameIDPolicy with a Format containing the provided value. If the receiving IdP can not fulfill this requirement it should return an error response.
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 should return an error response.
attributeIndex^3.3	string		If set, populates the AttributeConsumingServiceIndex XML attribute in the request
template	base64-encoded SAML <AuthnRequest> message)		If supplied, the eventual SAML request is constructed based on the message supplied, apart from per-request information or settings supplied directly in the configuration or as parameters. Allows a message to be constructed externally with extensions or dynamic content, and then re-issued by the SP.

Example

Example of an Embedded AuthnRequest Template

<SessionInitiator type="SAML2">
    <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="foo" Version="2.0" IssueInstant="2012-01-01T00:00:00Z">
        <samlp:RequestedAuthnContext Comparison="exact" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml:AuthnContextClassRef>https://federation.org/ac/type1</saml:AuthnContextClassRef>
            <saml:AuthnContextClassRef>https://federation.org/ac/type2</saml:AuthnContextClassRef>
        </samlp:RequestedAuthnContext>
    </samlp:AuthnRequest>
</SessionInitiator>