Page tree
Skip to end of metadata
Go to start of metadata

The majority of the independent pieces of SP configuration can be made re-loadable, on a per-configuration basis. This is generally done by configuring a series of common attributes and child elements, the specifics of which depend on whether the configuration is "local" or "remote", which in practice means in a local file or on a remote web server.

While it may seem attractive in some cases, it isn't advisable to use the "remote" resource capability to load configurations from a central location. It's possible, but it comes with a large number of caveats, including significant security and reliability considerations that tend to make it a bad idea.

For one thing, you MUST sign the XML file with an enveloped digital signature to secure this in the general case. The SP doesn't validate a server certificate if a TLS connection is used (*), so it assumes a signature is used. The only reason this isn't simply a failure is that it's assumed some deployers might want to leverage a trusted network and skip the signature, so the capability was left in to do so. The logging around this is probably insufficient.

Secondly, the management of the backup file is not aware of whether the file content was actually usable. That is to say, if a remote copy of a file is able to be downloaded and parsed as well-formed XML, or even validated against a known schema, the backup copy will be overwritten. If the XML subsequently is found to be a grocery list and not a valid configuration file for the intended purpose, it's too late to do anything about it, and a restart will just pick up the overwritten backup. This is endemic to the design of the code because of how low in the stack the feature is implemented, and there are no plans to change this.

Simply put, don't use the feature unless you really understand the caveats.

(*) It is possible to overcome the TLS limitation by means of the <TransportOption> feature to explicitly configure the libcurl library with a static set of certificates to use as trust anchors.

Typically the core configuration (shibboleth2.xml) is an exception to this, in that it defaults to a local file that is monitored for reloadability in a standard fashion. Since it's the "root" of the system, there typically is no XML configuration that itself describes where it lives and how to treat it, but technically it is possible to control the handling of that resource using more advanced settings.

Some component configurations are commonly defined "inline" within the shibboleth2.xml file itself, notably the RequestMapper, and this is usually possible any time a component supports this reloadability feature (e.g., you can define metadata inline if you really want to, or even rules for attribute mapping). In most cases, using a separate file is just simpler.

Common Attributes

Identifies the component for logging purposes.

Remote location of an XML resource containing the required configuration. The SP does not verify the transport (i.e. it does not verify the X.509 certificate presented by the remote server when HTTPS is the transport).

local path

Path to a local file containing the required configuration

booleanfalseIf true, XML validation is performed when loading the resource
booleantrueIf a path attribute is used, the local file is monitored for changes and reloaded dynamically. This incurs some runtime overhead for locking, so should be disabled if not needed.
time in seconds0If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource. If 0 (the default), no reloading occurs. This incurs some runtime overhead for locking, so should be left at 0 if not needed

Synonym for maxRefreshDelay

local path
If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead
local path
Path to a certificate containing a public key to use to require and verify an XML signature over the resource. The certificate's other content is ignored.
If present, the name is supplied to the <TrustEngine> used to verify an XML signature over the resource. A certificate containing the name must be available in the verification process (typically inside the signature).

Child Elements

These child elements are typically only used when relying on a remote configuration resource and are for advanced use cases.





0 or 1Used to require the presence of a top-level signature over the entire resource and to control the verification process


0 or 1

Used to require the presence of a top-level signature over the entire resource and to control the verification process.

Mutually exclusive with the <TrustEngine> element and the certificate attribute.


0 or moreProvides low-level control over the library used to remotely access the resource

  • No labels