Current File(s): conf/intercept/context-check-intercept-config.xml
Format: Native Spring
The "context-check" intercept flow is an example of how to use an intercept to interrupt processing and either continue or halt processing based on the state of the "context tree" that makes up the state of the request. A common use case for this feature is to impose authorization rules at the IdP to work around the limitations of a service that either does not implement any authorization or does not provide an adequate user experience in the event of failure. A frequently cited example of the latter is Google Apps for Education. Must be their limited budget.
Everything about a request is tracked in the tree of context objects (or can be injected into the condition bean applied), so there is no "hidden" information. Anything is on the table for examination, including:
- information about the relying party
- information about the user, the user's session, the user's authentication state, or attributes
- environmental information from the client request
- any configuration/rules you define and inject with Spring
The only configuration involved with this flow is to define the condition you want it to evaluate, and possibly adjust the user interface result in the event of failure.
The bean named shibboleth.context-check.Condition in intercept/context-check-intercept-config.xml must be defined by you with the condition you want to apply. The bean must be of type Predicate<>, but beyond that, it can do anything. Note that this is the same type signature as the conditions discussed in the ActivationConditions topic, so the examples there may help you. Non-programmers may be particularly interested in the scripted examples.
The common authorization usage for this flow is reflected in the example condition you will find in the file. It demonstrates the use of a built-in condition called a SimpleAttributePredicate, which evaluates the request for the presence of particular attribute(s) and optionally value(s) through a simple map. Each map entry is the ID of an attribute, and the map values are a list of attributes to check for (or you can use an asterisk as a wildcard to indicate that any value is acceptable). Refer to the Javadoc for additional details.
The other half of the configuration of this flow is the result. Obviously success simply causes things to proceed in the usual fashion, but failure will produce an event called "ContextCheckDenied". The IdP's built-in ErrorHandlingConfiguration treats that event as a "local error", meaning that processing is halted and an error page displayed.
The event is mapped to a default error message using the standard machinery, which you can adjust, but producing the right response for a lot of different (possibly unrelated) scenarios will quickly become hard to manage. You will probably want to define your own events, and to do that, you need to create your own copy of this flow.
While you absolutely can use this flow directly, it will often become unwieldy to try and combine every possible use for this feature into a single condition to evaluate. One reason is the user interface problem discussed above. So you may find it more fruitful to actually copy it into your own version in "user-space" and create multiple versions of it for different purposes. That way each one is simple, self-contained, and easier to maintain.
To create a new version of this flow called "intercept/mycheck", do the following (commands shown are basic Linux/Unix, idp.home is your installation directory):
Next, edit the new mycheck-flow.xml file and change the location of the
<bean-import> to "mycheck-beans.xml".
Then edit the new mycheck-beans.xml file and remove the
<alias> elements (the last two) and replace them with your own condition bean. The condition bean must be called "ContextCheckPredicate", but is otherwise the same as what you would define the shibboleth.context-check.Condition bean to be if you were using the built-in example.
Finally edit conf/intercept/profile-intercept.xml and add the bean
<bean id="intercept/mycheck" parent="shibboleth.InterceptFlow"/> to the existing list of beans to make the system aware of your new intercept flow.
That's all you have to do, but you may want to change the event returned by your copy so that you can map it to a different error message. To change the event, edit your new mycheck-beans.xml file and replace the reference to "ContextCheckDenied" with the name of your event. It can be anything, more or less. Then you'll need to add that event to a file named conf/intercept/intercept-events-flow.xml. The default file includes a commented example for an event called "MyCustomEvent".
You can create as many copies like this as you want. Each one will have its own name, and you must individually enable these flows using the
postAuthenticationFlows profile configuration bean property as described in the ProfileInterceptConfiguration topic.
As an example, you might create a copy of this flow for use with Google and enable it in a relying party override for that SP like so:
|shibboleth.context-check.Condition||Predicate<>||Condition evaluated by the system-supplied intercept flow to decide whether to continue|