The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NativeSPReloadableXMLFile

Owned by Scott Cantor
Last updated: Jun 29, 2016 by trscavo@internet2.edu
3 min read

Most native SP configuration files are implemented as "reloadable" resources, which gives them a common set of capabilities. In most cases, components with detailed configurations (i.e. more than just a single element) can be configured using any of:

  • a local file (usually in /etc/shibboleth
  • a remote file (hosted via http or https)
  • inline (for more compact information that's easier to maintain inside shibboleth2.xml)

When not inline, various common attributes can be used to control (or disable) the monitoring and reloading of information when it changes. When inline, the entire shibboleth2.xml configuration is itself a reloadable resource.

No matter which method of access is used, the XML instance being referenced typically has a common root element that depends on the component being configured, so the actual XML varies by component.

Attributes

  • url (absolute URL)
    • Remote location of an XML file containing the required configuration element. The native SP does not verify the transport (e.g. the SP does not verify the X.509 certificate presented by the remote server when HTTPS is the transport).
  • uri (absolute URL)
    • Synonym for url.
  • path (local pathname)
    • Path to a local XML file containing the required configuration element.
  • pathname (local pathname)
    • Synonym for path.
  • file (local pathname)
    • Synonym for path.
  • filename (local pathname)
    • Synonym for path.
  • validate (boolean) (defaults to false)
    • If true, XML validation is performed when loading an external XML file.
  • reloadChanges (boolean) (defaults to true)
    • If a path attribute (or a synonym) 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.
  • reloadInterval (time in seconds)
    • If a url attribute (or a synonym) is used, this attribute sets the time between attempts to download a fresh copy of the resource. If omitted or 0, no reloading occurs. This incurs some runtime overhead for locking, so should be disabled if not needed.
  • backingFilePath (local pathname)
    • If a url attribute (or a synonym) 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 and all the configured filters are run on the backing file.

Version 2.4 and Above

  • id (string)
    • Identifies the plugin, currently used for logging purposes.
  • certificate (local pathname)
    • Path to a certificate containing a public key to use to verify a top-level signature over the resource. The certificate's other content is ignored.
  • signerName (string)
    • If present, the name is supplied to the <TrustEngine> used to verify a top-level signature over the resource. A certificate containing the name must be available in the verification process (typically inside the signature).

Child Elements

When supplying configuration inline, a single child element is typically required, but the exact element depends on the component being configured.

Version 2.2 and Above

For remote resources, you may supply <TransportOption> elements to control the behavior of the transport layer used to fetch the resource. This can be used to adjust timeouts, for example.

Version 2.4 and Above

For remote resources, you may supply one of the following elements (or the certificate attribute as a shorthand) to require the presence of a top-level signature over the entire resource and to control the verification process:

  • <TrustEngine> (optional)
    • Allows signatures to be validated using the more comprehensive trust engine interface, which allows for a richer interpretation of signature and key information.