Administration

Overview

The IdP includes a small (at present) number of internal administrative functions to help manage and monitor the application, and this number is expected to grow in the future. As with the more well-known features, the administrative features are also built using Spring Web Flow.

Prior to V3.3, these flows were ad hoc. They now share a common framework and configuration, and are expected to be built in accordance with this documentation to ensure consistent support for authentication and authorization features.

Relying Party and Profile Configuration

As described in the GeneralArchitecture topic, the root of the context tree for any of the profile flows is the ProfileRequestContext class,and this is also true for administrative flows. Unlike the more traditional profile flows, there is no typical "relying party" to associate with them, and they are not enabled in the same way.

Instead, an administrative flow's profile URI is used as a stand-in for the typical "relying party ID" and a mocked up context tree is created to reflect this. A net.shibboleth.idp.profile.context.RelyingPartyContext child context to the ProfileRequestContext is created to hold the profile URI, and a profile configuration object (this object is in fact the same bean defined in admin.xml for the flow). No RelyingPartyConfiguration is populated.

Programming Guide to Administrative Flows

Top-level flows exposed to the outside world are divided into profile flows and administrative flows. Administrative flows are essentially any feature that doesn't take advantage of the full relying-party abstraction for their configuration. They're assumed to be on or off generically and behave somewhat uniformly, although in practice any amount of intelligence could be built into the flows themselves if desired.

As a top-level flow, there is no special naming convention for administrative flows, but they are all defined to the system with a bean of type net.shibboleth.idp.admin.AdministrativeFlowDescriptor in a list in conf/admin.xml.

See AdministrativeConfiguration for more information on this "deployer-facing" aspect of the system.

Administrative flows must inherit from an abstract flow named "admin.abstract" by specifying it in the <flow> element's parent attribute.

The Spring bean file for a new flow MUST define a String-valued bean called shibboleth.AdminProfileId containing the URI identifying the feature. The URI should be one under the control of the author, like a Java package name would be.

The first action defined in the flow should typically be:

<action-state id="InitializeProfileRequestContext">
	<evaluate expression="InitializeProfileRequestContext" />
	<evaluate expression="'proceed'" />
        
	<!-- Branch to parent flow. -->
	<transition on="proceed" to="DoAdminPreamble" />
</action-state>

This will establish the context tree and carry out all of the pre-defined behavior configured by the deployer, including (optionally) authentication and attribute resolution.

A state called DoProfileWork must also be defined to resume control of the flow, after which processing is entirely arbitrary. At that point, the context tree will be as follows:

Most of the contexts above are optional and only present if authentication or attribute resolution are performed.

Authorization

Flows are free to implement any form of security they choose, but the access control service is a convenient mechanism to use. For simple use cases involving a single access check, flows may evaluate the action expression CheckAccess to run the named policy exposed by the deployer via the flow descriptor bean (and the name of that policy can itself be derived at runtime if desired).

In addition, two beans of type Function<ProfileRequestContext,String> may be defined:

• shibboleth.AdminOperationLookupStrategy
• shibboleth.AdminResourceLookupStrategy

These functions are called to derive the operation and resource to supply to the access control decision performed by the CheckAccess action.

Error Handling

The system as a whole follows a fairly standard pattern: flows signal the "proceed" event to allow execution to continue, and any other event will propagate into the error handling machinery of the system (this can have different effects depending on the flow, e.g. a SOAP fault, a JSON result, an error page, etc.).

By default, administrative flows will dump errors into the system's default error handling view(s). Web service interfaces that need to ensure non-HTML output can override this behavior by defining a pair of flow-scoped variables at the top of the flow with the flow states to transition to:

<on-start>
	<evaluate expression="'CustomView'"  result="flowScope.ErrorState"/>
	<evaluate expression="'CustomView'"  result="flowScope.AuditedErrorState"/>
</on-start>

The literal expressions are the state names to use, which must be defined somewhere in the flow definition, usually a view or end state. Separate states can be defined based on whether the request should be audited, if desired, but the custom state is responsible for invoking the WriteAuditLog action.