Advanced Configuration
Note, this is an advanced configuration feature. Most deployments can rely on the <SSO> shorthand element.
The <SessionInitiator> element is used to configure handlers that are responsible for initiating the process of authentication to the SP and establishing a session with it. This represents what single sign-on architecture refers to as an "SP-initiated" flow, where a browser starting at the application end needs to be referred to the IdP to login and then return with the appropriate information to login.
The specifics of the authentication request process vary by protocol, and the internal SessionInitiator API allows the SP to be extended with many request protocols. The handler is responsible for all of the details associated with making the request.
A special characteristic of this kind of handler is that it often runs implicitly as a result of the first access to a protected resource (e.g. when the requireSession content setting is in effect). For other kinds of use cases, such as the "passive/lazy session" feature that enables an application to defer the creation of a session, a simple (and extensible) protocol is implemented local to the SP software to enable applications to invoke these handlers using a standard HTTP redirect with a query string. See the Initiator-Protocol section below).
The ability to configure multiple SessionInitiator handlers and to combine them in chains allows the deployer to control the selection of particular SSO protocols when more than one can be used, and to implement various approaches to IdPDiscovery (the process of figuring out which IdP to use in a federated environment).
Types of SessionInitiators
Broadly speaking, there are two kinds of SessionInitiators: protocol handlers and discovery handlers.
A protocol handler requires that the name of an IdP (that is, its entityID) be supplied to the handler so that its metadata can be obtained to determine whether and where it supports a particular protocol. The entityID can be supplied in a number of ways, including via query string, a hardcoded <SessionInitiator> attribute, or via a content setting applied to the resource.
By contrast, a discovery handler requires that the IdP not be known, and is responsible for interacting with the browser in some way to determine the IdP to use. It can do this in any way it wants to, such as examining cookies, interacting with the user, or by redirecting the browser to some other server.
Specific Initiators are defined by the type= attribute, each type specifies its own attributes as well as the common ones. Some initiators allow child elements. The following types are available by default. More may be added as plugins
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. |
Initiator Protocol
The Shibboleth SP does not have an application API per se, but the SessionInitiator mechanism supports a simple redirect protocol capable of triggering, and influencing, the creation of authentication requests.
This protocol supports a small set of query string parameters that correspond to identically named attributes that can be supplied either directly on a <SessionInitiator> element or as content settings on a per-resource basis.
When a query string parameter is used, it overrides any other source of the same setting/property.
Common Query String Parameters
Not all SessionInitiator handlers support all the possible parameters. Query String Parameters which are specific to a protocol are listed under the Session Initiator.
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. |
Examples
The redirection examples shown are illustrated by way of the HTTP Location header that would be returned to a client by an application. Refer to your programming environment's documentation for information on how to generate redirects and produce such a header. Note that you should always be sure to URL-encode any parameter values that you append.
The examples also assume that a SessionInitiator exists at the location "/Login", which is the usual default.
The most common scenario is to simply ask for a login while providing a resource to return the client to afterwards. Typically, this is the resource from which the redirect is generated.
Request a Session and Return to https://sp.example.org/resource.asp
Location: https://sp.example.org/Shibboleth.sso/Login? target=https%3A%2F%2Fsp.example.org%2Fresource.asp
Another common case is to specify the IdP to use. This is a simple way to implement user selection of an IdP from among a small set, for example clicking on a choice of logos. Not coincidentally, the SAMLDS handler is implemented by routing the result of the discovery process back to itself with the entityID parameter set.
Request a Session Using the IdP Named https://idp.example.org/idp/shibboleth
Location: https://sp.example.org/Shibboleth.sso/Login? target=https%3A%2F%2Fsp.example.org%2Fresource.asp& entityID=https%3A%2F%2Fidp.example.org%2Fidp%2Fshibboleth