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

AdministrativeConfiguration

Owned by Scott Cantor
Last updated: Nov 05, 2021
6 min read

Current File(s): conf/admin/general-admin.xml (V4.0), conf/admin/admin.properties (V4.1+)
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.

The IdP includes a framework for defining administrative flows that in addition to supporting basic access control also supports 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 configuration 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

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 admin/general-admin.xml file is where all supported administrative flows are (very minimally) described to the system.

The file contains a Spring list bean named shibboleth.AvailableAdminFlows. The beans in this list are of a specific class, AdministrativeFlowDescriptor, with a small number of intrinsic properties along with a set of inherited settings that overlap with some of the options available in relying-party.xml for defining profile behavior, including:

  • 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/)

V4.1 introduces Modules, and some of the individual administrative flows have been converted into modules that can be enabled and disabled. This approach is addressed within the pages that document all the flows. Most of the flows are so simple as to require little or no additional configuration, and so are not in modules and are "always" available though subject to access control.

The primary means of configuring most of the simple options is via the file admin/admin.properties. Most of the settings in this file are commented out and defaulted, so setting the ones you need generally involves uncommenting them.

Every administrative flow known to the system auto-registers itself with defaults that can be overridden by setting corresponding properties, generally with the naming convention "idp.feature.setting".

For reference or for those whose understanding may be aided by seeing the actual wiring, you can see the XML that allows all the properties to slot in here, as well as in the Reference section of each individual flow's documentation page, but it's not essential to using the properties or understanding what they do.

Upgrading from V4.0 and Earlier

The information above focuses on the "as-delivered" V4.1 defaults, which are considerably 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 replaced by simpler properties, with a new file (admin/admin.properties) added. Most of the properties in this file are commented out and largely ignored because they are superseded by the beans in the original admin/general-admin.xml file, which has been removed from new installations (but is still processed when present).

With this release, all beans of type AdministrativeFlowDescriptor 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 administrative flows are wired up internally with properties used to control settings rather than XML.

For compatibility and for those who favor XML, any flow descriptor bean inside a list named shibboleth.AvailableAdminFlows with a particular c: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 admin/general-admin.xml, setting idp.searchForProperties to "true" in idp.properties, and setting any properties corresponding to non-default settings applied in the XML will provide equivalent behavior (and hopefully be easier to understand).

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 the authenticated property on its descriptor bean in admin/general-admin.xml

You can use the defaultAuthenticationMethods bean setting to control which login flows are used and how they're used by specifying required custom Principal(s) 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.

You can mark a flow as requiring authentication with a flow-specific idp.feature.authenticated property in admin/admin.properties

If you need to control how authentication is done, this requires reverting to XML by overriding the built-in bean defining the flow with your own copy nested inside a shibboleth.AvailableAdminFlows list bean. You can define these beans in global.xml and you can easily copy the bean that defines a specific flow by referencing the system's copy of the bean (see here).

Then you would create a defaultAuthenticationMethods setting to the bean, specifying required custom Principal(s) 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.

You can mark a flow as requiring authentication with a flow-specific idp.feature.authenticated property in admin/admin.properties

If you need to control how authentication is done, you can control this with a set of idp.feature.defaultAuthenticationMethods properties that are analagous to the “supportedPrincipals” property syntax used with the various authentication flows in authn.properties.

With this release, you can also configure post-authentication interceptor flows via idp.feature.postAuthenticationFlows properties. The ability to run these flows was missing prior to this release.

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 do not support non-browser access during authentication. 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 authentication features that only 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.

The others include:

Reference