The main points to remember are these :
- Standalone Fault Handlers for a policy are used to catch all ABORT cases in a policy.
- ABORT cases occur where a filter cannot run properly, e.g. it cannot connect to the User Store so it has no way to authenticate the user.
- Failure cases occur when the filter returns a negative result, e.g. the user gave the wrong password so the user was not authenticated; the message was larger than the configured largest allowable message, the message did not validate against a Schema, the XML Signature did not verify, etc. These are all FAIL cases.
- Fault Handlers are NOT invoked when such a failure case arises since you may want to treat a failure case as part of the normal decision-making logic of the policy.
- For example, you may have a single policy that allows clients to authenticate over HTTP Basic, SSL, or WS-Security Username and Password. In this policy, we 1st attempt to authenticate the user using SSL. If this FAILS, we then try to authenticate the user using HTTP Basic. If this FAILS, we then try to authenticate using WS-Sec. In such cases you don’t want the Fault Handler to be invoked for the FAILURE cases. Instead you decide on a separate course of action for each failure cases by using failure paths.
The best practices for using fault handlers in policy shortcuts are as follows:
- For illustration purposes, let’s assume we have a top-level policy called “Father”, which calls into a “Son” policy via a Policy Shortcut.
- First of all, to handle ABORT cases, we place a fault handler in each policy - so one in “Father” and one in “Son”.
- So if any policy within the “Son” policy ABORTS, the “Son” fault handler is called; likewise, when a filter in the “Father” policy ABORTS, the “Father” fault handler is invoked.
- Secondly, to handle FAIL cases in the “Son” policy, we must remember that the FAIL status is passed up the call stack to the “Father” policy - it can therefore be caught in the “FATHER” policy by placing a failure path on the Policy Shortcut filter to the “Son” policy.
- At the end of this failure path, you should place a Policy Shortcut to a policy that returns appropriate Fault messages for the “Son” policy. So the logic of the top-level policy reads - “If any of the filters in the “Son” policy fail, call the “Son” fault policy”.
- Therefore, in general, you can handle the FAIL case of any filter in a Policy Shortcut (e.g. “Son”) by hanging a failure path linked to a “Fault Policy” (e.g. Set Message -> Reflect) off the Policy shortcut filter in the calling policy (e.g. “Father).
- So with these steps you are handling all ABORT cases in the Policy Shortcuts and also any FAIL cases in the Policy Shortcuts.
- The fault handler in the top-level policy will be invoked for all ABORT cases in the top-level policy (i.e. “Father”).
- It is also important to note that if a filter in the “Father” policy fails and it does NOT have a failure path associated with it, the Fault handler for the top-level will be invoked. So you use this strategy to catch failure cases in the top-level policy.