FormPOSTRecovery

The Hub plays the functional role of handling the preservation and recovery of form data per the Agent FormPOSTRecovery feature.

Here be Dragons

Before going any further, let’s note the obvious: this is a denial of service attack waiting to happen because there’s no way to guard this feature, so it is disabled by default. The form submission is definitionally unauthenticated or it wouldn’t need to be handled specially, so there is nothing whatsoever to stop a client from feeding massive numbers of form submissions into an Agent and causing a form preservation attempt to be made, and in the default configuration the Hub’s memory will be exhausted very quickly. (This is, notably, also true with the legacy SP and shibd.)

in practice, using this feature assumes the use of some form of semi-persistent StorageService. While this is better than using the Hub’s in-memory storage, it’s not all that much better. While in principle it might be possible to implement this feature using HTML storage to put the data into the client, this is quite complex to pull off and is not currently supported or planned.

Enabling

There are a number of properties available in conf/sp/sp.properties that globally control this feature; some of them correspond to Agent interface properties that can be adjusted on a per-Agent basis if desired. The Java properties, and where applicable the coresponding Agent bean property, are noted below.

To enable the feature, the only required steps are:

1. Uncomment and set sp.postData.preservation = true

   1. Alternatively you can set a Spring bean property on a specific Agent bean (see Reference below)

2. Assuming you don’t want the Hub to be taken down trivially with a DoS attack, configure an appropriate “external” server-side StorageService in conf/global.xml.

3. Uncomment and set sp.postData.StorageService to the name of the bean created in step 2.

If you skip step 3, do be aware that the default storage will be in Hub memory.

User Interface

The Velocity HTML template that the Hub will populate with the form data to “replay” to the Agent site is internal to the software by default, much as the SAML binding templates are in the IdP. The resource path is sp-server-impl.jar:/templates/sp/post-replay.vm and a pair of additional empty stubs are included much as in the SAML binding case:

• sp/add-html-head-content.vm

• sp/add-html-body-content.vm

You can place like-named resources in views/templates to override them.

Character Encoding Considerations

This is not an exhaustive discussion of the PhD level discourse that it would take to understand the issues around character encoding on the web, but suffice to say that while the standards bodies at this point all assume that UTF-8 is used universally, that’s not reality. But when it’s not, you’re going to have problems at best, and we can try to mitigate it at most.

The problem is that even if one assumes that the body of a request is covered by the HTTP-specified Content-Type, you can’t assume the same of the URL, and/or any data embedded in the URL in a query string. HTTP URLs and headers do not have a defined character encoding, nor does the Content-Type itself apply to them.

As a result, if the Hub needs to manipulate the URL, such as to place it in a form’s action attribute, it has to know the Character Encoding of the data to get it converted into a Java String accurately. While the Hub assumes the use of UTF-8, if it is known that a given Agent is operating with a different encoding scheme, you will need to set that with the characterEncoding bean property on that Agent. The Hub will use that encoding when it decodes URL-encoded data from either the URL or body so that it can reproduce the original form fields.

Java supports a lot of encodings using short labels for them that the code can convert into the underlying CharacterEncoding object.

This is a particular concern for this feature because the Hub is required to operate on the data as Strings, whereas in many other scenarios it leaves the data in the form of byte arrays to prevent having to impose an encoding on it.

Reference

Java properties can be assumed to apply globally to all Agent beans unless explicitly set on a particular bean.