Before You Begin
General Configuration Guide
Currently, all configuration is performed through standard Spring
<beans> files. Because pipelines are really just a collection of stages we'll start there and then move on to defining the actual pipeline.
The following stages read in information from various sources and add that information to the collection of items to be processed. You pipeline definition will usually start with one of these.
This stage allows you to define a static set of items that are added to the processing collection.
This stage reads one, or more, XML files from the filesystem and adds the document org.w3c.dom.Element, for each document read, to the item collection.
This stage reads an XML file from a Spring
DOM Processing Stages
The following stages operate on item collections containing org.w3c.dom.Element elements.
Examines all XML element text content and all XML attribute values in the item for the presence of a CR character. These can only appear in an XML document as the result of an explicit " " sequence, and can trigger an issue in the Shibboleth SP. If a CR character is detected, an net.shibboleth.metadata.ErrorStatus is added to the item, allowing subsequent stages to highlight the occurrence or to remove the item.
This stage strips out all instances of a specified element.
This stage strips out all instances of a specified element that do not contain other elements.
|This stage strips all elements and attributes in the specified XML namespace from each document in the item collection.|
This stage schema validates each org.w3c.dom.Element in the item collection.
This stage signs each org.w3c.dom.Element in the item collection.
This stage validates the signature(s) present on each org.w3c.dom.Element, or its descendants, in the item collection.
This stage evaluates each org.w3c.dom.Element in the item collection and removes those items that match a given XPath v1.0 expression.
SAML Processing Stages
The following stages operate on item collections that contain org.w3c.dom.Element that are SAML elements. Most stages operate on
This stage filters the types of
This stage takes a collection of
This stage adds an net.shibboleth.metadata.ItemId, containing the entity ID of an entity descriptor, to an item's metadata.
This stage filters entity roles from a collection of
This stage generates an ID for
This stage processes each
This stage processes each
This stage removes the
This stage sets a
This stage sets a
This stage validates that each the
MDRPI Processing Stages
The following stages operate on item collections that contain org.w3c.dom.Element that are SAML elements; they implement functionality related to the SAML V2.0 Metadata Extensions for Registration and Publication Information Version 1.0 specification. Most stages operate on
This stage extracts each entity's registration authority from a collection of
Item Metadata Stages
The following stages operate upon net.shibboleth.metadata.ItemMetadata associated with a given Item.
This stage filters out Items that are "tagged" with a particular ItemMetadata
This stage terminates processing if an Item is "tagged" with a particular ItemMetadata
Pipeline Structure Stages
The following stages are used for creating advanced pipeline structures (e.g., splitting one pipeline into multiple pipelines).
This stage compose multiple stages in to a single named and reusable unit.
This stage takes an item collection, and generates a number of new collections which are then passed on to associated pipelines for further processing.
This stage combines the results of multiple pipelines.
This stage splits a given collection in to two collection, runs each through a pipeline, and then merges the two collections back together afterwards.
The following stages are miscellaneous stages that just don't fit in to a category at the moment.
This stage executes a JSR-223 compliant script against each item in the item collection.
This stage serializes the content of an item collection out to file be means of an net.shibboleth.metadata.ItemSerializer.
Pipelines are defined as anything that implements the net.shibboleth.metadata.pipeline.Pipeline interface but, for most cases, the only implementation you'll need is the net.shibboleth.metadata.pipeline.SimplePipeline.
To configure this pipeline you must set the following properties:
In general, it's often not advantageous to halt the processing when on part of a given input is invalid. Usually you just want to mark it as invalid, proceed on, and remove the invalid content when you're done. Stages that do this will mark items with instances of net.shibboleth.metadata.StatusMetadata. You can then use the item metadata stages listed above to filter out, log, and/or terminate processing based on the status of the item.
Some errors, such as when attempting to read in XML data that is invalid, are considered fatal errors and will halt the processing of the pipeline.
Spring Specific Information
All stages and pipelines and some other objects (e.g., parser pools) must be initialized before use and Spring provides a couple options for doing this.
The easiest option is to add the attribute
default-init-method="initialize" to the root
<beans> element in your configuration. This will cause Spring to call the
initialize() method on any bean that has one.
Alternatively, if you need very fine-grained control for some reason, you can add the attribute
init-method="initialize" to every bean that requires initialization.
Spring provides extensions to the standard
<beans> notation through custom namespaces. In particular, the util extension can be very helpful when you need to construct collections of things. Just be sure to add the appropriate namespace declaration on the root
<beans> element if you use this extension.
In most cases, anywhere you can put a direct value (e.g., a int, a string) you can also use a Spring expression. This can be helpful if you want to compute or derive a value.
Of particular note, you can use the type operator,
T(...) to get access to a
java.lang.Class instance for a given type. For example:
When working with Spring it is sometimes difficult to convert from some string designation of an object into the object itself (e.g., changing the file path for a private key into a
PrivateKey object). The following factory beans are available to help with this:
Bean that produces a org.w3c.dom.Document given a file path and a parser.
Bean that produces a java.security.PrivateKey given a file path.
Bean that produces a java.security.PublicKey given a file path.
Bean that produces a java.security.cert.X509Certificate chain given a file path.
Bean that produces a java.security.cert.X509Certificate given a file path.