ExternalInterceptConfiguration

Current File(s): conf/intercept/external-intercept-config.xml (V4.0), conf/idp.properties (V4.1+)
Format: Native Spring, Properties (V4.1+)

1 Overview
2 General Configuration
3 API
4 Reference

Overview

The "external" interceptor flow is analagous to the External login flow, but for interceptors. It allows an interceptor to be implemented outside of the IdP's Spring WebFlow architecture and routes through a bridge generally implemented in a Java servlet or JSP page, but can be combined with additional redirects out of and then back into the IdP for additional development flexibility.

Once control is transferred to the external path, the IdP has no control over what happens. While the sensitivity of this feature is much less than with the authentication use case, it's still the deployer's responsibility to ensure the external code does what it's meant to do.

General Configuration

Use conf/intercept/external-intercept-config.xml to configure this flow.

The shibboleth.intercept.externalPath bean defines the flow redirection path to the resource that's used to perform the external interceptor's logic, by default a context-relative location. It must be a resource with access to the container session. Modify as needed to match the location of your external interface (see the documentation on flow redirects).

You may also dynamically derive the path to use, typically so that it can vary based on aspects of the request, by defining a bean named shibboleth.intercept.externalPathStrategy of type Function<ProfileRequestContext,String>

The idp.intercept.External.externalPath property defines the flow redirection path to the resource that's used to perform the external interceptor's logic, by default a context-relative location. It must be a resource with access to the container session. Modify as needed to match the location of your external interface (see the documentation on flow redirects).

On upgraded systems, the legacy file conf/intercept/external-intercept-config.xml may be removed if the property is defined in place of the original bean.

You may also dynamically derive the path to use, typically so that it can vary based on aspects of the request, by defining a bean (e.g., in global.xml) named shibboleth.intercept.externalPathStrategy of type Function<ProfileRequestContext,String>

API

The ExternalInterceptor class makes up the interface between the external code and the IdP. The general flow is:

Call ExternalInterceptor.startExternalInterceptor(HttpServletRequest), saving off the result as a key.
Do work as necessary. Any redirects must preserve the key value returned in step 1 because it must be used to complete the flow later.
Set request attributes to communicate the result of the interceptor back (likely just an event, if not successful).
Call ExternalInterceptor.finishExternalInterceptor(String, HttpServletRequest, HttpServletResponse). The first parameter is the key returned in step 1.

A JSP implementation is below. It works as is, but is obviously not doing anything interesting.

External interceptor example in JSP

<%@ page pageEncoding="UTF-8" %>
<%@ page import="net.shibboleth.idp.profile.interceptor.ExternalInterceptor" %>
<%@ page import="net.shibboleth.idp.profile.interceptor.ExternalInterceptorException" %>

<%
try {
    final String key = ExternalInterceptor.startExternalInterceptor(request);
    
	// If not successful...
    request.setAttribute(ExternalInterceptor.EVENT_KEY, "CustomEvent");

    ExternalInterceptor.finishExternalInterceptor(key, request, response);
     
} catch (final ExternalInterceptorException e) {
    throw new ServletException("Error processing external interceptor", e);
}
%>

Inputs

On first access to the external resource, the request attributes below will be set.

Name	Type	Function

Name	Type	Function
opensamlProfileRequestContext	ProfileRequestContext	Access to full request context tree

Outputs

Name	Type	Function

Name	Type	Function
event	String	ID of event to signal as result of the flow (defaults to "proceed" for a successful/continue outcome)

Reference

The beans defined in conf/intercept/external-intercept-config.xml follow:

Name	Type	Default	Description

Name	Type	Default	Description
shibboleth.intercept.externalPath	String	contextRelative:intercept.jsp	Spring Web Flow redirection expression for the resource
shibboleth.intercept.externalPathStrategy	Function<ProfileRequestContext,String>		A function that returns the redirection expression to use for the resource

The following bean may be defined in conf/global.xml:

Name	Type	Description

Name	Type	Description
shibboleth.intercept.externalPathStrategy	Function<ProfileRequestContext,String>	A function that returns the redirection expression to use for the resource

The following properties may be defined in idp.properties:

Name	Default	Description

Name	Default	Description
idp.intercept.External.externalPath	contextRelative:intercept.jsp	Spring Web Flow redirection expression for the resource