ProfileInterceptConfiguration

Current File(s): conf/intercept/profile-intercept.xml (V4.0), conf/relying-party.xml
Format: Native Spring

1 Overview
2 General Configuration
- 2.1 Defining Interceptors
  - 2.1.1 Upgrading from V4.0 and Earlier
- 2.2 Enabling Interceptors
  - 2.2.1 Example enabling intercepts for the SAML SSO profiles
- 2.3 Developing Interceptor Flows
3 Reference
- 3.1 Beans

Overview

An interceptor is a Spring Web Flow that can be run as a subflow at specific points during the processing of a request to the IdP to do work. It allows behavior to be customized without replacing core code.

There are currently three different "interception" points in the profile flows:

Inbound message processing
Post-authentication during SSO profiles
Outbound message processing

The inbound and outbound hooks are not commonly used by deployers. In contrast, the post-authentication hook is a very fruitful injection point for supporting many useful features. Several predefined examples come with the software, and can be used as examples to develop your own, though this is a development task, not just a matter of configuration.

General Configuration

Defining Interceptors

There are significant differences in the OOB approach to configuration for new installs of V4.1 compared to V4.0 or upgraded systems. The tabs below (and elsewhere in the page) provide the relevant information for each version, and where applicable information on taking advantage of new approaches after upgrading.

The intercept/profile-intercept.xml file is where all supported interceptor flows are (usually minimally) described to the system.

The file contains a Spring list bean named shibboleth.AvailableInterceptFlows. Descriptors are of a specific class, ProfileInterceptorFlowDescriptor, and generally the other options are handled with properties or with other XML configuration files.

The id property of each descriptor is not arbitrary. It MUST be prefixed by "intercept/" and it corresponds to a web flow definition. The predefined beans correspond to built-in flows. Creating a new flow involves not only describing the flow in this list, but ensuring the id matches a flow definition created inside flows/intercept/. Specifically, creating the custom flow "intercept/foo" requires that the flow definition file be named flows/intercept/foo/foo-flow.xml.

V4.1 introduces Modules, and most of the individual interceptor flows have been converted into modules that can be enabled and disabled. This approach is addressed within the pages that document all the flows.

Every interceptor flow known to the system auto-registers itself and generally any other settings are documented on those individual pages.

For reference or for those whose understanding may be aided by seeing the actual wiring, you can see the XML here, as well as in the Reference section of each individual flow's documentation page, but it's rarely essential.

Upgrading from V4.0 and Earlier

The information above focuses on the "as-delivered" V4.1 defaults, which are changed from earlier versions, and apply out of the box only to new installs. Upgraded systems, while they may contain combinations of old and new files, by design function the same as they used to for compatibility, and the new bits are generally ignored/overridden by the older settings.

With V4.1, the use of XML to configure many basic features has been minimized and the original intercept/profile-intercept.xml file has been removed from new installations (but is still processed when present).

With this release, all beans of type ProfileInterceptorFlowDescriptor are automatically recognized, obviating the need to define them by hand, which was the main purpose of the XML file. Instead, all of the built-in interceptor flows are wired up internally, and any settings required are (and, for the most part already were) handled with properties in the conf/idp.properties file.

Any flow descriptor bean inside a list named shibboleth.AvailableInterceptFlows with a particular p:id set will supersede the internally wired bean for that flow (and the log notes this at startup). A bean defined stand-alone outside the named list will not reliably replace the internal version.

For those wishing to migrate from the older approach to the newer approach (this is not required), removing intercept/profile-intercept.xml and setting any properties corresponding to non-default settings applied in the XML will provide equivalent behavior.

The following interceptor flows are provided with the software:

Enabling Interceptors

The three interception points above correspond to three properties that can be specified on the profile configuration beans in the RelyingPartyConfiguration. Each property is a list of intercept flow IDs (excluding the "intercept/" prefix) to run.

All profile configurations include a pair of properties, inboundInterceptorFlows and outboundInterceptorFlows, for specifying inbound and outbound interceptors. The profile beans typically auto-declare the right inbound interceptor flow to run to provide the appropriate security checks; these interception points should generally be left to their default values.

Authentication profile configurations (e.g. CAS, SAML Browser SSO and ECP) include a postAuthenticationFlows property for specifying the ordered list of interceptors to run after most of the work of the system is done but before any outbound message/response has been generated. They run after the user has logged in and after any user attributes have been resolved and filtered; essentially all that's left is the production of a response, so this is an opportunity to affect the result that will be produced (or prevent one altogether).

Example enabling intercepts for the SAML SSO profiles

    <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                <bean parent="Shibboleth.SSO" p:postAuthenticationFlows="#{{'attribute-release', 'terms-of-use'}}" />
                <ref bean="SAML1.AttributeQuery" />
                <ref bean="SAML1.ArtifactResolution" />
                <bean parent="SAML2.SSO" p:postAuthenticationFlows="#{{'attribute-release', 'terms-of-use'}}" />
                <ref bean="SAML2.ECP" />
                <ref bean="SAML2.Logout" />
                <ref bean="SAML2.AttributeQuery" />
                <ref bean="SAML2.ArtifactResolution" />
                <ref bean="Liberty.SSOS" />
            </list>
        </property>
    </bean>

Developing Interceptor Flows

Refer to the ProfileHandling developer material for more technical details on developing interceptor flows.

Reference

Beans

Bean ID	Type	Function

Bean ID	Type	Function
shibboleth.AvailableInterceptFlows	List<ProfileInterceptorFlowDescriptor>	List of flow descriptors enumerating the interceptor flows available to the system (supplanted in V4.1 by autowiring of ProfileInterceptorFlowDescriptor beans, but you may need to create this bean if you wish to extend/alter the system-defined beans)
shibboleth.InterceptFlow	ProfileInterceptorFlowDescriptor	Abstract parent bean for defining new flow descriptor beans