DefiningApplications

This is an overview of the process and Spring bean(s) involved when adding Application overrides to an Agent, using the Agent Resolver service, and some of the basic settings supported. A detailed reference to the supported settings is also available.

What are Applications?

An Application is an abstraction carried over from the legacy SP, a unit of configuration/behavior bound to specific web content by a deployed Agent. Agents indicate at runtime when making requests to the Hub which “Application” they want the request handled under. This is not something the Hub “validates” or checks in any way; it is up to the Agent to determine with its configuration and it signals the Hub of its requirements in the messages it sends. If there is no corresponding Application defined in the Agent configuration in the Hub, the request fails.

In turn, the Agent doesn’t control what the behavior or settings are for a particular Application; that is controlled by the Hub deployer when configuring them.

This is the main difference between the legacy SP and the new version; before there was a single configuration that controlled both aspects of this concept, while it is now separated by a software boundary, and possibly by a management boundary.

Use of this feature is intended to be exceedingly rare, because it is difficult to configure and use successfully, and it is only rarely the only or best way to solve a particular problem. This is even more true now because of the Java-based Hub’s support for Metadata-driven configuration and the flexibility to use scriptlets to derive settings at runtime, neither of which the legacy SP supported.

Default Applications

The configuration is geared around each Agent connecting all requests to a single “default” Application that is automatically used and defined on both the Agent and Hub so that it is essentially invisible and can be ignored other than as a Java interface that defines the settings that can be controlled. This is accomplished by ensuring that each Agent bean inheriting from shibboleth.sp.Agent exposes its default Application instance. You can simply apply settings as needed to it, the Agent will automatically make requests against it, and you can ignore the whole concept. This is what you should do in virtually all cases.

Given this, why support the concept at all?

Compatibility is a consideration, but “just in case” is the real answer. Through Spring’s flexibility, it is possible to maintain the possibility to exploit this feature for unforeseen reasons without it complicating routine use. If it had not been, the feature would most likely have been removed completely regardless of compatibility.

What has generally happened is that when unusual scenarios have arisen, the use of overrides was a safety valve for allowing things that wouldn’t be possible to predict ahead of time, and then in future verions we have enhanced the SP to allow them to be addressed without the use of overrides. But the damage was usually done by then, and a lot of legacy configurations remain more complex than necessary. The hope is that because the understanding of requirements now is far beyond what it was in 2001, that we’ve already made enough enhancements to prevent it from being a need in the vast majority of cases.

We are very committed to ensuring that if there is a future use case where overrides make the most sense, we will try our best to develop better approaches even if this requires additional code. The “ease” with which we can deliver updates to the Hub via the plugin mechanism, and the relatively fewer deployments of the Hub possible within a large deployment, helps with this goal.

Application Features

The Application interface is not itself all that extensive but it acts as a pointer to a lot of the functionality that the Hub uses when processing requests, such as the various services for Attribute processing and SAML Metadata resolution. Other notable settings control high level processing of SSO, mostly specifying an authenticating authority (IdP/OP/etc.) to use if not all Agents are using a single one.

In addition, Applications expose their default RelyingPartyConfiguration settings, and implement a resolver for additional RelyingPartyConfigurations (in this case the relying party being the authenticating authority in use).

Defining Overrides

An Application override is always defined in the context of a specific Agent. While Spring allows beans to be defined in such a way that multiple Agent beans could reference a single override, this is disallowed in the code to prevent problems with the complex inheritance model supported.

Each override has an identifier that is only required to be unique within a given Agent, and can only be connected to by the corresponding Agent deployments. So you can name them anything, including reusing existing override designations that may be configured for use by another Agent.

Overrides are defined inside an Agent bean’s applications property, which is a Collection of objects implementing the Application interface. A pair of parent beans are provided for defining new overrides:

• shibboleth.sp.Application

• shibboleth.sp.Application.NoInheritance

The difference between the two beans relates to the inheritance model that allows overrides to generally inherit many settings from their parent Agent, so the former bean is the most common one that would be used. The latter allows the override’s various settings to be “reset” to their defaults and not inherited in that manner.

Example

For example’s sake, assume that the default configuration of the Hub is to use SAML, but for a small subset of content we wish to exclude SAML and use only OpenID. Normally this would be an Agent-wide decision, but for illustration’s sake, assume it is being done for only a subset of an Agent’s content. An override would be one way of controlling this.

Various SAML settings here are omitted under the assumption they would be set via Java properties for “global” use across multiple Agents. The example shows only the Agent containing the override and some of those settings.

(Note, the OpenID settings are preliminary at this stage, but the point of the example is the override, not the specifics.)

In this example, the override is customizing only the sessionInitiators, tokenConsumers, and profileConfigurations settings exposed by the Application interface.

On the other end of this example, there is an Agent connecting to this definition by authenticating with a service account named “SA-shibs-example” and passing up (under specific conditions) an application ID of “oidc-app” in its requests.