SPConfig

The top level of the shibboleth2.xml file is a an <SPConfig> element that contains one each of several other top-level elements, each representing a category of SP configuration, and optional extensions. Each of these is described in its own section, linked below under child elements.

The root element can also contain a grab-bag of miscelleneous settings that tend to be global in nature or just don't fit anywhere else, and you don't normally have to touch them.

The core configuration file is a Reloadable XML File but in most cases you don't really manipulate that because by default the "first" file the SP loads is defaulted to be from a local file with the expected name, and the reloadChanges attribute is defaulted (making the SP detect changes and reload the file at runtime).

It is possible to override the default behavior when it comes to acquiring and handling this file, but the documentation for that is TBD.

Reference

Attributes

The following may be specified.

Name	Type	Default	Description

Name	Type	Default	Description
logger	local pathname		Optional setting for a property configuration file that defines logging behavior for the entire system. It is normally only used in syslog environments that would permit all processes in the system to send events to a common location because it overrides the `logger` property in the `<OutOfProcess>` and `<InProcess>` child elements (including when they're omitted).
clockSkew	time in seconds	180	Shibboleth, like most distributed security systems, depends on clock synchronization between servers. Limiting the difference in time between when an assertion is issued and delivered helps mitigate several potential attacks. However, some amount of time difference needs to be permitted to allow the client to transfer the assertion from the IdP to the SP and for small time discrepencies. This attribute sets the maximum difference allowed between any two server clocks.
unsafeChars	string	#%&():[]\`{}	Overrides the set of characters considered unsafe when substituting data into HTML templates used for errors, SAML message transmission, etc. Certain characters are always considered unsafe, but the rest can be adjusted.
allowedSchemes	whitespace-delimited list of strings	"http https"	Overrides the set of URL schemes/protocols to permit for redirection or generated form actions.
langFromClient	boolean	true	If true, the client's Accept-Language request header is used to determine how to process language-aware content.
langPriority	whitespace-delimited list of strings		Supplies a list of language tags to use when processing language-aware content, in the absence of client information or to break ties.

Child Elements

The following child elements can be specified and make up the bulk of the configuration. Many of these elements can be, and are, omitted. The associated pages describe the default settings used when various elements are omitted.

More complete examples of many of the omitted elements can be found in the example-shibboleth2.xml file, which is included with the software but not used directly.

Name	Cardinality	Description

Name	Cardinality	Description
<Extensions>	0 or 1	Allows for system-wide extension libraries to be loaded. This is rarely used because most extensions come in separate in-process ("lite") and out-of-process versions that limit the libraries loaded into web server processes to avoid symbol conflicts.
<OutOfProcess>	0 or 1	Deals with configuration and extensions of the `shibd` daemon, which manages state and does most of the heavy lifting. Defaulted as noted.
<InProcess>	0 or 1	Contains settings governing the portion of the SP that runs inside the web server, as well as configuration of that web server. Required for Microsoft IIS integrations in order to define IIS site mappings and general module configuration.
<Listener>	0 or 1	Pluggable extension point for Listeners other than the two provided with the software.
<UnixListener>		Listener implementation that relies on a Unix domain socket. Default on non-Windows systems.
<TCPListener>		Listener implementation that relies on a TCP socket. Can be used across a pre-secured network, but this is not recommended due to the overhead involved. Default on Windows systems.
<StorageService>	0 or more	Configures the storage of information that must persist across requests, like the SessionCache and ReplayCache. When omitted, an in-memory plugin identified as `id="mem"`, will be configured.
<DataSealer>	0 or 1	Configures the component that handles secure storage of data in client-side cookies in support of other features, primarily the SessionCache session recovery feature
<SessionCache>	0 or 1	Configures the caching of typically cookie-based sessions that bind attributes and SAML assertions for use by web requests. When omitted, the StorageService-based cache will be used on top of the default StorageService, with other options defaulted.
<ReplayCache>	0 or 1	Configures the caching of message identifiers for short periods to prevent replay attacks. If omitted a default/arbitrary StorageService will be used.
<ArtifactMap>	0 or 1	Configures the short-term storage of XML messages bound to artifacts for communication to partner sites by reference. If omitted an in-memory version with default settings will be used.
<RequestMapper>	0 or 1	Maps incoming web requests to configuration settings and the Application to associate with them. Generally needed only with Microsoft IIS.
<ApplicationDefaults>	1	Defines most of the runtime behavior of the software when the SP processes SAML assertions, extracts data, and establishes sessions. Most of your changes, if any, will be here.
<SecurityPolicyProvider>	1	Controls the low-level security and XML processing performed during the runtime operation of the SP. Mostly used to supplement the list of cryptographic algorithms to block, or in rare cases, to permit those blocked by default.
<ProtocolProvider>	0 or 1	Plugin used to supply default binding/endpoint information for supported protocols to drive the simplified content of the `<Sessions>` element. This is an "auto-wiring" trick that allows the visible configuration to be more minimal by hiding the details in a separate file without preventing them from being changed in unusual cases.
<TransportOption>	0 or more	Allows implementation-specific options to be passed into the SOAP client transport code. Only for experts.
<ds:Signature>	0 or 1	A digital signature over the entire file. Used in conjunction with the reloadable file support for verification of signed resources, usually only relevant for remotely-acquired configuration files.