The Shibboleth IdP V4 software will leave support on September 1, 2024.

WarningInterceptConfiguration

This feature requires V4.1+ of the software.

Current File(s): conf/intercept/warning-intercept-config.xml
Format: Native Spring, Velocity

Overview

The "warning" interceptor flow is a generalization of the older "expiring-password" flow that supports an arbitrary number of conditions and warning views at the same time in support of multiple use cases without requiring duplication of and creation of custom webflows by the deployer. It can support the original expiring password use case but is not limited to that. Nor in fact is the original flow limited to that use case, but this makes that generality clearer and corrects some confusing behavior in the original.

All interceptors are enabled or disabled on a per-relying-party basis using properties in the profile bean(s) you want to enable the flow for. See the ProfileInterceptConfiguration topic for an example.

Enabling Module (V4.1+)

For V4.1+, configuring and using this feature requires that you first enable the "idp.intercept.Warning" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.

(Windows) C:\opt\shibboleth-idp> bin\module.bat -t idp.intercept.Warning || bin\module.bat -e idp.intercept.Warning (Other) $ bin/module.sh -t idp.intercept.Warning || bin/module.sh -e idp.intercept.Warning

General Configuration

The primary configuration involved with this flow is to define the condition(s) you want to evaluate, and which custom view template to display. Unlike the "expiring-password" flow, this implementation uses the more logical convention that the warning condition should evaluate to true to indicate that a warning should occur.

The bean named shibboleth.warning.ConditionMap in conf/intercept/warning-intercept-config.xml must be defined by you with the condition(s) you want to test and the additional information needed to control the warning process. Each map entry represents a unique warning, and the map is iterated over to test for and present all applicable views.

The keys in the Map are view template names resolved relative to views/intercept/ (e.g. the key "mywarning" would normally resolve to a template in idp.home/views/intercept/mywarning.vm

The Map values are beans of type Pair<Predicate<ProfileRequestContext>,Duration>> (the complex type is needed to associate both the necessary settings with the map key).

The first element of the pair is the bean to evaluate to test the warning condition. If it returns true, the warning is applied and if it returns false, the warning does not apply to the request.

The second element of the pair is a Duration value representing the interval between warnings. Setting this to a zero value will cause the warning to appear on every request, while any other value represents an interval during which the warning will not appear.

A cookie for each warning entry in the map is used to track the last warning time, so clearing cookies will reset this behavior. The prefix of the cookie name can be changed if desired, with the map key added to the prefix to construct the unique cookie name, allowing different intervals and tracking per warning type.

Views

The view templates can largely be modeled on existing views, particularly the expiring-password.vm file, which illustrates how to advance the flow forward. For reference the variables generally available to the views are described in https://shibboleth.atlassian.net/wiki/spaces/IDP4/pages/1265631615 though they are not specific to Velocity-based views.

Replacement of Expiring Password Flow

This flow can essentially replace the original one by reversing the sense of the condition applied in that particular flow's configuration, and utilizing "expiring-password" as a map key (or just renaming the view template).

Reference

The following bean is expected to be defined in conf/intercept/warning-intercept-config.xml:

Bean ID

Type

Description

Bean ID

Type

Description

shibboleth.warning.ConditionMap

Map<String,Pair<Predicate<ProfileRequestContext>,Duration>>

Map of conditions to test, warning intervals, and view names to render

The following property can be defined in any of the consumed property files (such as idp.properties):

Name

Default

Description

Name

Default

Description

idp.warning.notifyCookiePrefix

shib_idp_warn_

Prefix of cookie(s) to use to prevent repeated viewing of the warning page(s)