New Configuration Summary

Toggles between backward-compatible regex matching against the entire candidate string, and the more typical, Apache-style partial regex matching such that only a portion of the candidate has to match. Full matching is auto-anchored, and tends to require a lot of extra .* expressions to “eat” additional content.

No other values currently defined, extension point allowing for alternative implementations of the bulk of the agent library’s configuration and handling of various components. The old SP has a similar extension point but it’s never been used and the setting won’t normally appear.

Space-delimited list of URL schemes permitted to appear in URLs when redirects are issued.

Space-delimited list of Apache AuthTypes (unused otherwise) to process as though they were “shibboleth”, which is always included and is the default AuthType the module processes.

Causes “unset” variables to carry a designated value instead of being “cleared/unset”.

Usually enabled if headers are used, enables logic that tries to detect header spoofing/smuggling by detecting a pre-existing header matching a header name controlled by the agent.

On some platfiorms like Apache, this can be set to a random value that reduces the chance of false positives from the spoof checking logic on internal sub-requests, but generally this should be left unset unless experiencing issues.

Whether to try and catch all C++ runtime exceptions or only “known” exceptions. Failure to catch an exception terminates a process with prejudice.

Pointer to IIS-specific agent settings (this is a separate file because of how the Site mappings are defined). The file extension may be “ini” or “xml”, and the latter implies the format used by the older SP software’s <ISAPI> element.

Instructs the agent to load an extension DLL/shared library from a file path (the property key). The boolean value is an indicator about whether failure to load the extension should be fatal to startup.

Controls the logging implementation to use. The three expected types (pending others) are as shown, with the obvious defaults based on platform. In more advanced systems, this would be the “Appender” to use. Notably, much of the critical logging is in the hub, not the agents, as it was before with shibd.

Sets the default logging level if not overridden for a category.

Controls whether syslog is opened at agent startup (false is used if the web server relies on syslog as well). Ignored by other logging types.

Sets the syslog facility as an integer. The default is the LOG_USER bitmask value. Ignored by other logging types.

Basic means of overriding logging level for specific categories, but notably this isn’t hierarchical as with more full-featured logging libraries. We expect to flatten out some of the nesting of categories to reduce the impact of that.

Controls the agent/hub remoting service to use. Generally defaulted as appropriate for the platform.

Used to connect to operations implemented by the agent’s hub.

Identifies agent to hub for configuraton/authentication purposes.

If set, overrides default User-Agent header sent with requests to hub.

Type of authentication used by agent when connecting to hub, will be extended with additional options as supported/warranted.

Enables capture of a named cookie to support caching of authentication with the hub.

Sets a non-defaulted cipher string to inject into a TLS implementation to limit ciphers or protocols used. The format will depend on the type of remoting service and the TLS library in use (most commonly OpenSSL’s format when not using Windows).

Specifies file to use as a CA list when connecting over TLS to hub. For the CurlHTTP type, this must be a file with PEM-encoded CA certificates.

Flag controlling use of chunked content encoding. When false, the request is buffered to determine a content length to supply instead of using a read callback to pull data to send.

Connection timeout in seconds.

Overall timeout in seconds.

Source of agent secret for shared secret authentication to hub.

Used with secretSourceType=File, path to file containing secret. Trailing linefeeds/etc. are omitted.

Used with secretSourceType=Env, name of environment variable to extract secret from.

Controls the session cache implementation to use. These are “expected” types, but the only certainties are the first type, using the file system or calling on the hub to access a Java-based StorageService implementation such as a database.

Controls the RequestMapper implementation to use. The XML type essentially points to a reloadable external XML file to hold the configuration, while the Native type is for Apache to turn off the extra mapping layer (same as in V3).

For the XML type, specifies the local file containing the XML.

Whether to monitor the file for reloads, which occur in the foreground after taking a read lock, based on file modification time. C++-14 support is required for this code to be active and doing so introduces shared locking to the use of the component.

This section contains one or more key/value pairs mapping a “handler configuration ID” to a file defining the handlers that are active for a request that maps to that ID. This section can be omitted in most cases, in which case the default handler configuration will be found in handlers.ini. If this section is defined, then no default mappings are created or assumed.

IIS Role assigned to any authenticated user.

Space-delimited list of attribute IDs use values will be assigned as additional IIS roles.

Bypasses Site-based mappings (see below) to determine canonical request scheme, host, and port. Unsafe to disable unless not using the RequestMap. Equivalent to Apache’s UseCanonicalName command.

Controls whether attributes are passed to an application as Server Variables.

Controls whether attributes are passed as HTTP Headers, should never be enabled and if done for compatibility, applications should be remediated to avoid the need.

Default matches the status of the useHeaders flag. Causes all non-alphanumeric characters to be removed from the names of all SP-controlled headers, as their presence makes header smuggling much harder to guard against due to IIS implementation choices (bad ones, that is).

Optimizes ignoring non-handler requests when a default or static handlerURL is used, as is generally the case.

The canonical name reported to the SP for any requests to this site. Needed because SERVER_NAME in IIS is untrusted information controlled by the client.

Overrides the scheme reported to the SP for any requests to this site. Needed only when the physical scheme differs from the client-observed logical scheme, i.e. when virtualizing a site.

Overrides the port reported to the SP for any physical HTTP requests to the site. Needed only when the physical port differs from the client-observed logical port, i.e. when virtualizing a site.

Same as port, but is applied for any physical HTTPS requests to the site.

Whitespace-delimited list of alternative hostnames that should be accepted as valid if requested by a client.

Space-delimited list of CIDR expressions to match against the client address to authorize access to the handler.

Space-delimited list of CIDR expressions to match against the client address to authorize access to the handler.

Space-delimited list of settings to pull from the RequestMapper based on the request that should be passed to the hub for processing the session request. This allows an arbitrarily extensible set of protocol options to be signalled without awareness by the agent code. The default will be determined closer to completion of SAML and OIDC support but will include the legacy SAML options (e.g., ForceAuthn).

Same as above but for query string parameters to the handler directly. These can be independently controlled for security purposes to limit what can be passed from the client to the handler (and thus be under insecure control).