NativeSPShibbolethXML

Most of the native service provider's configuration options are found in shibboleth2.xml, located in the SP's main configuration directory. This location varies by installation, but will commonly be /etc/shibboleth/shibboleth2.xml or /opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml.

For help with initial configuration, check the Getting Started topic. This page is a general reference to help with advanced use.

The primary configuration file consists of 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.

<SPConfig xmlns="urn:mace:shibboleth:sp:config:2.0"
	xmlns:conf="urn:mace:shibboleth:sp:config:2.0"
	xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
	logger="syslog.logger" clockSkew="180">

    <Extensions/>

    <OutOfProcess/>

    <InProcess/>

    <Listener/>

    <StorageService/>
    <SessionCache/>
    <ReplayCache/>
    <ArtifactMap/>

    <RequestMapper/>    

    <ApplicationDefaults id="default" policyId="default"
        entityID="https://sp.example.org/shibboleth"
        homeURL="https://sp.example.org/index.html"/>

    <SecurityPolicies/> <!-- Earlier Releases -->
    <SecurityPolicyProvider/> <!-- 2.4 and Above -->

    <ProtocolProvider/> <!-- 2.4 and Above -->

    <ds:Signature/> <!-- 2.4 and Above -->

</SPConfig>

Attributes

logger (local pathname)
- Optional setting for a log4cpp/log4shib 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)
- 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) (Version 2.2 and Above)
- 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. The default "adjustable" set is #%&():[]\`{}

allowedSchemes (space-delimited list of strings) (Version 2.3 and Above)
- Overrides the set of URL schemes/protocols to permit for redirection or generated form actions. Defaults to http and https.

langFromClient (boolean) (defaults to "true") (Version 2.5 and Above)
- 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) (Version 2.5 and Above)
- 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

Starting with Version 2.4, many of these elements are optional and are omitted from the default configuration file. More complete examples suitable for copying can be found in the example-shibboleth2.xml file. The associated pages describe the default settings used when various elements are omitted.

<Extensions> (zero or one)
- Allows for system-wide extension libraries to be loaded. This is not commonly used because most extensions come in separate in-process ("lite") and out-of-process versions.

<OutOfProcess> (zero or one)
- Deals with configuration and extensions of the shibd daemon, which manages state and does most of the heavy lifting.

<InProcess> (zero or one)
- Deals with configuration and extensions of the web server module/filter component specific to each supported server.

<Listener> (zero or one)
- Configures the communication layer between the in-process and out-of-process components.

<StorageService>(zero or more)
- Configures the storage of information that must persist across requests, like the SessionCache and ReplayCache.

<SessionCache> (zero or one)
- Configures the caching of typically cookie-based sessions that bind attributes and SAML assertions for use by web requests.

<ReplayCache> (zero or one)
- Configures the caching of message identifiers for short periods to prevent replay attacks.

<ArtifactMap> (zero or one)
- Configures the short-term storage of XML messages bound to artifacts for communication to partner sites by reference.

<RequestMapper>(zero or one)
- Maps incoming web requests to configuration settings and the Application to associate with them. Also connects the portable configuration layer with server-specific mechanisms like .htaccess files. Generally needed only with IIS.

<ApplicationDefaults>
- Provides for configuration of protocol behavior, session policy, error handling, and attribute handling. All requests into a server using Shibboleth are mapped by the RequestMapper, or web server commands, to the settings in the corresponding <ApplicationDefaults> or <ApplicationOverride> element for processing.

Shibboleth Applications

The majority of the SP's behavior is defined on a per-application basis. An application is an internal organizing concept that defines a set of configuration options for related sets of resources. These applications may or may not directly align with the web applications that are protected by the SP, but often do. For extensive discussion of this concept, refer to the NativeSPApplicationModel topic.

<SecurityPolicies>
- Deprecated. For versions prior to 2.4, this element controls the low-level security and XML processing performed during the runtime operation of the SP. Many different protocols and profiles can be handled by a Shibboleth SP. The various security checks that are performed can vary across and within these profiles but can generally be implemented by a common set of rules.

<SecurityPolicyProvider> (Version 2.4 and Above)
- Replacement for the <SecurityPolicies> element, this externalizes the information previously handled by that element behind a pluggable interface, typically an external configuration file.

<ProtocolProvider> (zero or one) (Version 2.4 and Above)
- Plugin used to supply default binding/endpoint information for supported protocols to drive the simplified content of the <Sessions> element.

<TransportOption>(zero or more)
- A "hole" in the transport independence of the system allowing implementation-specific options to be passed into the actual SOAP client transport. Only for experts.

<ds:Signature> (zero or one) (Version 2.4 and Above)
- A digital signature over the entire file. Used in conjunction with the new reloadable file support for verification of signed resources.