New Configuration Summary

Owned by Scott Cantor
Last updated: Dec 31, 2024
3 min read

This is a draft/parking lot for tracking the new SP configuration as it is being designed and implemented. All settings are subject to change. Most boolean settings can be set using XML syntax (as true, false, 1, or 0).

Most of the configuration is no longer reloadable in the style of older versions, with the exception of the two XML-based configurations.

Existing/Compatible

The XML AccessControl and RequestMapper syntaxes are structurally expected to remain mostly compatible/similar to V3, with the exception that the RequestMapper would be in a separate file (due to the surrounding configuration being non-XML-based, so embedding it no longer “fits”). The separate file is assumed to be rooted in a <RequestMap> element. AccessControl can be embedded in it as before, or placed in external files (more typically via the Apache module’s support for this).

The actual content settings in the RequestMap are likely to be altered, but it’s likely more will be aded than removed, as most of the settings that used to exist in other places will be migrated into the RequestMap (if they continue to exist).

Top-Level

The top-level file will be an INI file (conventionally in /opt/shibboleth-sp/shibboleth.ini). So far the following sections have been sketched out or implemented:

[global]

regexMatching = full | partial

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.

agentType = Default

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.

allowedSchemes = https http

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

extraAuthTypes = custom1 custom2

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.

[extensions]

<pathname> = true | false

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.

[logging]

type = console | syslog | windows

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.

defaultLevel = DEBUG | INFO | WARN | ERROR | CRIT

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

openSyslog = true | false

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.

facility = <int>

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

[logging-categories]

<category> = DEBUG | INFO | WARN | ERROR | CRIT

Basic means of overriding logging level for specific categories, but notably this isn’t hierarchical as with more full-featured logging libraries.

[remoting]

type = HTTP

Controls the agent/hub remoting service to use, this is the only type expected to be implemented.

[session-cache]

type = filesystem | storage | cookie

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.

[request-mapper]

type = XML | Native

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).

path = <pathname>

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

reloadChanges = true | false

Whether to monitor the file for reloads, which occur in the foregrund 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.

Examples

; shiibboleth.ini [global] regexMatching = partial [logging] type = syslog openSyslog = false defaultLevel = INFO [logging-categories] Shibboleth.AgentConfig = DEBUG Shibboleth.Agent = DEBUG [remoting] ... [session-cache] ... [request-mapper] type = XML path = request-map.xml reloadChanges = true