The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.

AdministrativeConfiguration

Current File(s): conf/admin.xml

Format: Native Spring

Overview

The IdP supports a small number of "administrative" functions (reloading configurations, the status page, attribute resolver diagnostics) that are exposed as simple web interfaces and as command line scripts. V3.3 includes a new framework for defining administrative flows that will support future development in this area.

In addition to the access control supported by earlier versions, it is now possible to enable the IdP's authentication and attribute resolution features before invoking administrative flows, and to apply access control policies based on user- or attribute-based rules.

In the majority of cases, there's no need to touch this file right now unless you want to do something unusual or exotic with the current administrative features to change their access control model. But it may be useful in the future as additional features are developed, or if you're developing your own features to extend the IdP.

General Configuration

Defining Administrative Flows

The admin.xml file is where all supported administrative flows are (very minimally) described to the system. This file is new in V3.3; in prior releases the flows included were ad hoc and essentially self-contained, so turning on and off certain features would require modifying the flows. The new framework allows certain features to be configured by the deployer, at the cost of requiring an explicit registration process, similarly to how authentication and profile interceptor flows are defined.

The file contains a Spring list bean named shibboleth.AvailableAdminFlows. Descriptors are of a specific class, and support a number of properties that can be set explicitly or derived with runtime functions/scripts:

  • whether to interpose authentication and/or attribute resolution
  • specific authentication flow or custom principal requirements (e.g., requiring MFA)
  • a named access control policy to apply
  • whether non-browser support is a requirement (this primarily impacts the kinds of authentication that can be done)

Each descriptor contains a constructor parameter named "id" that contains a URI uniquely identifying each flow to the system and that corresponds to the identifiers embedded in the flow implementations themselves (all of the IdP's delivered "top-level" flows are identified by URIs that are prefixed with http://shibboleth.net/ns/profiles/)

Authentication

The IdP does not at present rely on an "application session" in its own right; rather, each webflow is treated as a separate function to which a requester may have to authenticate itself in order to satisfy an access control policy. However, the IdP's own SSO functionality can be used to gloss over this behavior; to an end user it will usually appear as though he/she is signing on once and simply navigating to different features. A particular advantage of this approach is that step-up authentication is automatic (if you apply different requirements to different flows), since each administrative flow is free to express its own requirements and the IdP's existing capabilities will simply ensure that the right things happen.

You can mark a flow as requiring authentication with either the authenticated boolean flag or with an authenticatedPredicate on its descriptor bean.

Note that you can configure a different set of authentication flows for administrative access than for ordinary user access. Each profile can rely on a different set of login flows by setting the authenticationFlows property, although when the MFA flow is involved, this isn't as clear-cut and is usually unnecessary.

More commonly, you can use the defaultAuthenticationMethods property to indirectly influence which flows are used and how they're used by specifying a required custom Principal that the resulting authentication process must satisfy; this is the same mechanism used to attach similar requirements to services that can't request this for themselves using relying party overrides.

See the AuthenticationFlowSelection topic; essentially, the process of selecting the flow(s) to try is identical because to the IdP, the administrative flow is like a profile flow it's being asked to satisfy requirements for.

Browser vs. Non-Browser

By default administrative flows are considered to be "browser-supporting". What that means in practice is nothing, unless you turn authentication on. Then it matters for determining whether to behave in ways that would be expected to break a non-browser client. For example, a simple script should not need to navigate a login form, though it could supply basic-auth credentials. So if you turn authentication for a feature on, but you want to use only authentication features that work with a non-browser client, you would need to set the nonBrowserSupported flow descriptor property to signal this. Or you could even perform user-agent testing on the fly to set this by plugging in a condition script via nonBrowserSupportedPredicate.

Developing Administrative Flows

Refer to the developer material under Administration for technical details on developing your own administrative flows.

Supported Flows

As noted at the top, most of the current administrative features are actually more like REST-based WebInterfaces.

One additional flow has been added to V3.4, in support of an "attended restart" mode.

Reference

Beans

Bean IDTypeFunction
shibboleth.AvailableAdminFlows    List<AdministrativeFlowDescriptor>List of flow descriptors enumerating the administrative flows available to the system
shibboleth.AdminFlowAdministrativeFlowDescriptorAbstract parent bean for defining new administrative flow descriptor beans
shibboleth.OneTimeAdminFlow 3.4AdministrativeFlowDescriptorAbstract parent bean for defining new administrative flow descriptor beans for flows intended to execute only once

Notes

TBD