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
The following may be specified for all types of Session Initiator
Name | Type | Default | Description |
|---|---|---|---|
type | string | required | Plugin type name. |
Location | relative path | The location of the SessionInitiator (when combined with the base handlerURL). This is the location to redirect to when manually initiating a session using the Initiator protocol (query string) | |
id | string | optional | Identifies a SessionInitiator so that it can be referenced by the requireSessionWith content setting. |
isDefault | boolean | If true, establishes the default SessionInitiator used implicitly for content protected with the requireSession content setting. If none are labeled, the first is implicitly the default. | |
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. | |
relayState | string | Controls how information associated with the session request, primarily the original resource accessed, is preserved for the completion of the authentication process. Overrides the like-named attribute in the <Sessions> element. | |
acsIndex | string | This matches the index of the <md:AssertionConsumerService> element to use for the return message from the IdP. | |
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. | |
signing | one of | See Signing&Encryption. Controls outbound signing of XML messages and content subject to applicability to the protocol involved. | |
encryption | See Signing&Encryption. Controls outbound encryption of XML messages and content subject to applicability to the protocol involved. | ||
externalInput | boolean | true | Allows handlers to disallow the use of externally supplied parameters / input to drive them. The specific settings this influences will vary by handler, and by default the full range of settings supported can be supplied from outside the SP, typically using query string parameters or form submission. For particularly sensitive or important options, this setting can be used to block that support. This primarily applies to the "SAML2" handler but may be honored by any handler as it deems appropriate. |
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
The protocol independent parameters are
Parameter Name | Parameter Value Type | Description |
|---|---|---|
entityID | URI | The IdP to request authentication from. |
target | absolute URL | The URL to return the user to after authenticating. If unspecified, the homeURL attribute for the application is used. |
acsIndex | string | The index value of the <md:AssertionConsumerService> element to instruct the IdP to use in returning an assertion to the SP |
authnContextClassRef | whitespace-delimited URIs | Requests that particular authentication context classes be used by the IdP. |
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>