ContentSettings

A content setting is a configuration option that can be applied to a request based on its scheme, host, port, path, query string, or in some cases other properties. Within the Agent configuration, they appear in the Request Mapper configuration (typically the request-map.xml file). With some Agent implementations, notably Apache, they can also be applied with the Apache command ShibRequestSetting, which can appear in a lot of different areas of Apache’s configuration.

For the most part, the Request Mapper and Apache approaches are interchangeable and can be combined freely, though Apache commands are somewhat more reliable depending on other settings (e.g., UseCanonicalName), and they can be devolved to .htaccess files controlled by different staff who might not be given access to the Agent configuration itself.

Outside of Apache, there are currently no other supported mechanisms for defining them except the Request Mapper.

Many of these settings existed in older SP versions, which is noted in the tables, and for the most part should have similar or identical meaning. A few old settings are no longer supported or were renamed, and some new settings exist. Some “New” settings are newly supported as cotent settings and may have existed with essentially the same function in other parts of the older SP configuration.

Where did Applications Go?

By design, the bulk of the Agent configuration is intended to consist of content settings, since they allow for per-content behavior without requiring a lot of extra configuration “machinery” to get them associated with a request. In particular, deployers of older versions will notice that within the Agent there is no mechanism to define Applications or Application Overrides.

That is quite deliberate; whle the Hub recognizes this concept, any settings that existed in that layer have either been removed or were migrated into content settings. This eliminates an indirection layer that caused more confusion than anything else, even if it is in some cases more verbose without it.

Main Settings Reference

applicationId

Carry-over from the original SP design, this serves two purposes.

Local to the Agent, this value is used to segregate sessions. A session created with a particular applicationId setting in effect will be ignored during requests associated with a different setting. Multiple sessions may be created with a client at the same time, provided different applicationId settings apply during their creation.

This value is also attached to most requests to the Hub to allow Agent configuration at the Hub to be subdivided for customization. Since the Hub is primarily about SSO protocol handling, and the original Application concept in the SP was also largely to do with customizing SAML behavior, this is a natural step.

If not set, all requests carry a “default” ID; using any other value requires a shared understanding of the intent of a non-default value between the Agent and its Hub.

Note that application IDs are only unique and indeed meaningful in the context of a particular Agent; the value of “default” is the same regardless of the Agent since the Agent is also identified in any request it makes to the Hub. Similarly, a value of “custom” could mean entirely different things within a Hub depending on which Agent is using it, though of course that’s pretty confusing. In practice, a given Hub is likely to use non-default values for this setting as a generally “common” signal for some kind of behavior, such as using a particular authentication authority, using particular protocol settings, use of a particular key, providing different custom attributes, etc.

The need for this feature is often minimal, as it evolved to be in older versions, but it provides a degree of flexibility while avoiding Agent complexity that caused a lot of problems historically.

Also as before, use of this feature should be confined whenever possible to the host-level and not the path level and for the same reason; it’s only possible for the system to correctly process a SSO roundtrip if both the original request for a protected resource and the eventual request to the Hub for token validation are bound to the same applicationId setting. Failure to do so will cause no end of problems that are hard to understand and diagnose.

attributeConfigId

Directs the Agent to process attributes in a session with a non-default configuration.

See AttributeConfigurationSettingsfor details on using this setting; its value must correspond to a property key in the [attribute-configurations] section of the Agent.ini file.

attributeValueDelimiter

Specifies the string used as a delimiter when expressing multiple values of an attribute in a single header, variable, or other scenario involving a siingle string. Any extant copies of the delimiter in values will be escaped with a backslash in the resulting string (but not in any other direct access to the values such as when evaluating them for access control purposes).

Note that if the encoding Attrbute Configuration setting is set to “URL”, this character or string must be a value that will be fully URL-encoded because the values will not be checked for any extant instances of the delimiter and they will not be escaped, making splitting of the multiple values impossble. The default of a semi-colon is thus safe since it will be encoded and not collide with the delimiter after URL encoding is done.

authType

An Apache concept carried over into the Agent generally, a value of “shibboleth” activates the Agent to process requests.

It is common to install this setting globally, or at least at the highest level for which content is to be protected.

consistentAddress

Controls whether the client’s address is checked for consistency with the address information bound into a session.

A failed check invalidates a session.

cookieMaxAge

Overrides the MaxAge property set when issuing session cookies.

By default, the property is controlled (along with various other cookie settings) globally via the SessionCacheSettings.

If set to -1, cookies are issued with no attribute, indicating a non-persistent cookie stored in the browser’s session store (this is a carry-over from Java’s API and is a convenient signal value to use). Any positive value is a lifetime in seconds.

expireRedirects

Controls the addition of cache-preventing and expiration headers when issuing redirects to the browser to prevent mishandling and replay of old cached redirects.

handlerConfigId

Directs the Agent to process handler requests with a non-default configuration.

See HandlerConfigurationSettings for details on using this setting; its value must correspond to a property key in the [handlers] section of the agent.ini file.

This setting would typically be applied at the host level and allows a customized set of handlers to be installed for that host.

handlerSSL

Used in conjunction with the handlerURL setting, when true, it restricts handler requests to those made against a TLS-protected virtual host and the Agent will ignore requests made to non-TLS-protected hosts, passing them through to what will usually result in a 404 error.

handlerURL

Specifies the default prefix of most handlers in the system to optimize processing of requests and allow the Agent to compute the URL of a handler when necessary. The default matches the value of the comparable setting in the legacy SP for compatibility but is no longer required to be any specific value in particular.

Most Agent implications will have the capability to implement handlers that may live at URLs outside of this URL prefix but most do for efficiency reasons.

This setting is almost always a relative path, but may actually take any of these forms:

The second form will be instantiated based on the active hostname in a given request but with a fixed scheme and/or port, while the third form will always be relative a given request’s scheme, host, and port.

homeURL

Specifies a “default” resource location (almost always a relative URL) to direct a client to in cases in which no speciifc target resource exists or was able to be recovered during the processing of a request.

lifetime

Controls the cradle-to-grave lifetime policy applied to sessions when evaluated in the context of a particular request.

If 0, sessions may last indefinitely subject to other policy. Otherwise this specifies the amount of time in seconds since the creation of a session that it remains valid.

As a content setting, this allows session lifetime to vary from one request to another, and this should be considered when using different values that may be applied in the context of a single session.

logoutNotify

Enables a front-channel “notification” loop when logout occurs by routing the browser into one or more URLs prior to acting on a logout, so any active session will remain accessible during this process.

It is the responsibility of the application(s) at any such URL to avoid errors and redirect back to the value of the “return” query string parameter to continue or complete the notification process and eventually complete the logout.

logoutURL

Specifies a default location to redirect to after a logout completes. A “return” query string parameter may override this value at runtime. If not set, a basic response directing you to define a logoutURL setting will be displayed.

Note that it is not advisable to use the installed location to impart “essential” information to a user as in most non-local logout scenarios, this resource will not be visible to the user due to the requirements of implementing single logout protocols.

preservePostData

Controls the activation of an expensive feature to capture and preserve form submission data so that an authentication “round trip” from the Agent to an authenticating authority and back to the Agent will not interrupt the submission.

Only the application/x-www-form-urlencoded content type may be preserved by this feature; multi-part data is not supported.

This feature requires that a form submission (up to a maximum size) be transmitted to the Hub, stored via its configuration, bound to a cookie, and subsequently recovered and replayed via a custom HTML form as the final act of returning control to the original protected resource.

Off by default because this creates an unavoidable denial of service vector against the Hub’s storage layer, so should be enabled with care, particularly with a Hub not relying on an external storage medium as memory exhaustion will disable the Hub and the Agent very quickly.

postLimit

Limits the size of a POST body that the preservePostData option will attempt to preserve and recover.

redirectAllow

One or more whitespace-delimited URL prefixes of the form "scheme://hostname[:port]/". Used with subset of redirectLimit values (see below). Don't forget the trailing slash because e.g. specifying "https://example.com" also allows example.com.evil.com etc.

redirectErrors

Primary means of customizing error handling by triggering redirection to a specified URL.

The URL may (will?) contain parameters that provide some additional information about the error. The information is of course advisory and is subject to client manipulation, and should not contain sensitive values.

redirectLimit

Prevents the injection of redirect locations after login or logout that don't meet specific criteria, to prevent misusing the Agent to carry out phishing or exfiltration attacks.

"none" does no limiting ( Consider carefully before using this option as it can allow malicious use of your Agent as an open redirect). This was the default in older SP versions for compatibility reasons.

"exact" is the default, and requires that the destination match the exact scheme, hostname, and port of the handler performing the redirect.

"host" requires that the destination match the hostname of the handler performing the redirect.

"allow" requires that the destination's "scheme://hostname[:port]/" matches an allowed list of whitespace-delimited URL prefixes. Allows explicit permission to send the client off-host to external systems. The list of URL prefixes is set via the redirectAllow setting.

"exact+allow" combines the "exact" and "allow" policies above, without requiring explicit enumeration of the handler's virtual host details.

"host+allow" combines the "host" and "allow" policies above, without requiring explicit enumeration of the handler's host.

redirectToSSL

Specifies a port to redirect non-https requests to.

This is supplanted in most cases by existing web server features to redirect non-TLS requests but remains if needed.

REMOTE_ADDR

Name of HTTP request header to use to determine the client’s IP address in place of the usual REMOTE_ADDR server variable.

This is typically used only as a workaround for Agents that are not in a web server environment that already allows control of this value when load balancing or proxying traffic via the standard Forwarded header. This setting should almost always either be absent or set to “Forwarded”.

REMOTE_USER

List of attribute IDs from which REMOTE_USER should be set. The first attribute present, with a value, is used to populate REMOTE_USER. If multiple values exist, it is unspecified which is used. If none exist, or the setting is absent, REMOTE_USER will not be set.

requireLogoutWith

When applied to content, that content acts as a logout trigger point; if a session exists, the Agent will redirect the client to the URL specified in this setting, attaching a self-referential URL as a “return” parameter on the query string of the provided URL.

The resource at that URL is expected to redirect the client back to the “return” parameter (subject to approproate checks). The Agent will detect this and “break” the loop by passing control to the resource.

The URL may be relative or absolute, and is not subject to additional checks by the Agent to limit redirection as the setting is presumed to be under trusted control already.

requireSession

Controls whether to require a session for access to the resource.

When true, termed “active” protection, the Agent will interpose itself to initiate SSO request via the Hub with the expectation a response will later be submitted resulting in control returning to the same location (with a session).

When false, termed “passive” protection, if the Agent is enabled then it will process the request, “unset” any protected request headers if headers are in use, and process a session’s data if one exists. This allows applications to detect the presence or absence of a session on their own, allowing a single URL to handle both cases. Passive use generally requires more application awareness of the Agent and its behavior.

sessionCookieName

Allows part of the session cookie name to be overridden.

Typically the cookie name is automated and modified based on the applicationId setting in effect; this allows part of the name to be overridden, but the variable portion remains controlled by the Agent to allow sessions to be maintained properly.

sessionHook

Specifies a location to send the client after a session has been created (i.e., after login), but before transferring the client to the eventual final resource.

This is normally a relative path to ensure that the session will be visible to the hook script, but doesn't have to be. A hook can be used to validate something about the session to check its "fitness for purpose" before delivering the client to an application that may not offer sufficient error handling capability to do the job itself. A common example is checking for required attributes, which is a built-in feature for convenience.

The hook redirect will include two query string parameters, target and return. The target parameter contains the resource URL that will eventually be the client's destination, in case the hook cares. The return parameter is the location to redirect the client back to upon completion of the hook.

The hook MUST either redirect back, or failing that must take complete ownership of the client with no further processing needed by the Agent.

target

Allows the resource location 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.

timeout

Controls the inactivity timeout policy applied to sessions when evaluated in the context of a particular request.

If 0, sessions may last indefinitely subject to other policy. Otherwise this specifies an amount of time in seconds since the last known use of a session that it remains valid.

As a content setting, this allows session timeouts to vary from one request to another, and this should be considered when using different values that may be applied in the context of a single session.

Note the underlined word above: the actual last known use of a session is an estimated value that is updated based on a configured frequency via the storageAccessInterval setting. It is generally only as accurate as that interval and a timeout may occur later than expected based on that interval.

unset

This is a mechanism to “unset” properties at a particular level of the content tree if there is no way to override them naturally into a desired state. Most properties can easily be overridden instead of being unset, but this is a mechanism to catch any cases that don’t lend themselves to that. The value is a delimited list of other content settings that should be reverted to their absent or defaulted state.

useHeaders

Controls whether attribute data is published into request headers for a particular request.

Use of request headers is NOT recommended and is supported only for legacy compatibility.

useVariables

Controls whether attribute data is published into server variables for a particular request.

Protocol Request Options

Another set of “special” options exists that the Agent itself doesn’t consume directly but will optionally detect and forward to the Hub when processing requests for new sessions. These options are discussed, along with the controls available for limiting which ones can be used in the SessionInitiatorHandlertopic.

At present, they consist of (more will be defined during development of the OpenID support):

• authority

• entityID

• isPassive

• forceAuthn

• authnContextClassRef

• authnContextComparison

• NameIDFormat

• SPNameQualifier