Advanced Configuration
Note, this is an advanced configuration feature. Most deployments can rely on the <SSO>
shorthand element.
Identified by type="Transform"
, this initiator transforms an entityID
according to a set of permutations until IdP metadata can be found. No specific protocol support is assumed; the first entityID
for which a valid <md:IDPSSODescriptor>
can be found terminates the handler's activity.
This handler doesn't actually cause a response to the browser, but it generally runs first in a chain, and allows the entityID to be manipulated before other handlers run. It serves a variety of purposes, from transforming user input into an entity to acting as a kind of "redirect" mechanism that turns one entityID into another.
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 |
---|---|---|---|
alwaysRun | boolean | false | If false, the initial entityID value is looked up, and if metadata is found, the handler exits. Set to true to perform at least one transform on even valid entityID values. |
Child Elements
Name | Cardinality | Description | |
---|---|---|---|
<Subst> | 0 or more | Simple transform whose element content consists of a string containing the substring | |
<Regex> | 0 or more | Complex transform containing a |
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
There are no protocol specific parameters
Example
The example tries a sequence of transforms that allows any of the following to be turned into an InCommon IdP name (currently a URN containing a domain name):
the domain name itself (e.g.
osu.edu
)an email address from the domain (e.g.
foo@osu.edu
)a subdomain of the domain (e.g.
law.osu.edu
)
<SessionInitiator type="Transform"> <Subst>urn:mace:incommon:$entityID</Subst> <Regex match=".+@(.+)">urn:mace:incommon:$1</Regex> <Regex match="^[^.]+\.(.+)">urn:mace:incommon:$1</Regex> </SessionInitiator>