SAML2 SessionInitiator
Advanced Configuration
Note, this is an advanced configuration feature.Ā Most deployments can rely on theĀ <SSO>Ā shorthand element.
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 |
---|---|---|---|
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. |
authnContextComparisonĀ | One of: | exact | If set, inserts aĀ <samlp:RequestedAuthnContext>Ā element containing the comparison operator into theĀ <samlp:AuthnRequest>. |
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). |
attributeIndexĀ 3.3 | string | Ā | If set, populates theĀ AttributeConsumingServiceIndex XML attribute in the request |
Child Element
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 |
---|---|---|---|
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 | 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>
Ā