ApplicationOverride

Overview

The <ApplicationOverride> element overrides SP behavior for a set of resources that are associated with the override using the applicationId content setting. The association can be made via the RequestMapper component or native web server commands as in Apache.

The rule of thumb is that any settings you don't override inside the element will be inherited from the <ApplicationDefaults> element that surrounds the override. This is generally true, but there are exceptions and some of the rules get a little complex, so the specifics are covered down below and should address any questions about how the inheritance works.

Before getting into the gory details here, please be sure to read the ApplicationModel topic that explains the underlying concept of an "application" and how resources and applications relate. This topic is essentially a How-To guide with examples for implementing the configuration options introduced there.

Also be sure you really need an override. Most of the typical reasons people use them are not valid and they add unnecesary complexity to a deployment. By and large, you shouldn't need them unless:

• you're virtually hosting different applications on the same system

• AND you really need fundamentally different behavior for those applications

Some more guidance follows.

Valid and Invalid Reasons for Overrides

Here are some use cases where an additional application has to be defined:

• different metadata or security policy

• different attribute mapping or filtering rules

• different rules for session behavior, such as timeouts

Generally speaking, only the latter is a particularly good reason to bother. There are almost always better ways of using the SP that don't require different metadata or attribute behavior.

Here are some use cases that usually do NOT require an additional application be defined:

• overriding the entityID (i.e., exposing an additional logical SP from a single physical installation)

• use of a particular IdP or discovery service based on the resource

• use of different credentials (e.g., certificates) with different IdPs

• customized error handling

Some of those use cases did require overrides in older versions, but now there are a variety of enhanced options available via content settings. Instead of creating a bunch of extra XML configuration, you can simply set properties using Apache or the <RequestMapper> based on the virtual host or path, and change which IdP gets used (entityID), what the SP names itself (entityIDSelf), or change many other behaviors.

Establishing a New Application

Assuming you're unlucky and actually need to create an additional application in the configuration, it's a two-part process:

Step 1: Create and name the application via <ApplicationOverride> and the id property.

Each application has a simple identifier associated with it. The "default" application that corresponds to everything initially is simply called "default" (duh). When you create new applications, you need to give them simple names to refer to them in the second step below. Using short, simple names is best, but any string is fine. Once you decide on a name, you insert an element like so just inside the </ApplicationDefaults> closing tag (there are some new ways to define overrides described later, but this is the traditional way).

Initially the application doesn't do anything; there are no overridden settings and it may not even work properly, but we'll fix that later.

Step 2: Map the applicable resources using a matching applicationId setting.

The second step is to associate the resources that make up the new application (and the associated handler path) to an applicationId content setting that matches the id you chose in the previous step. There are two ways to do this (the simple examples apply to an entire virtual host being mapped to the new application, other examples will be shown later).

Mapping via Apache Commands (httpd.conf or equiv.)

Mapping via the <RequestMap> (shibboleth2.xml)

Obviously the former only works on Apache, IIS requires the latter approach. Apache commands are usually safer on Apache, because using the <RequestMap> will only work safely if you set the UseCanonicalName option.

As the comment above in the example notes, you MUST make sure that the SP handlers that are used with the application override are appropriately mapped to the same application ID as the resources. The handlers and resources are a unit.

Host vs. Path

A key issue to address when establishing additional applications is whether to organize applications by virtual host or by path. The reason for using paths is basically all about the overhead of virtual hosting, primarily in terms of having the ability to register them in your DNS and because of the need for additional certificates and IP addresses in most cases involving SSL.

Nevertheless, there are a couple of major reasons why the best thing to do is use virtual hosts: security and simplicity.

The security issue depends somewhat on your reasons for defining additional applications, but essentially any web resources that share a virtual host should be treated as being part of a single security "zone" because that's how browsers treat them. You cannot isolate applications that share a virtual host and keep them from seeing cookies restricted based on paths, and any scripts on a virtual host can manipulate the browser in order to leak information from one application to another. So if your reasons for the new application involve creating any real separation between resources, you have no choice but to use a different virtual host. Otherwise just don't bother.

The simplicity argument is related to how the SP software deals with separate applications, and the requirement (outlined here) that every application have a unique handlerURL prefix for its handlers.

When you use virtual hosting, there is no special handler configuration needed; you can simply inherit the default settings because the handlers will automatically be specific to each virtual host. When a request comes into https://myapphost.example.org/Shibboleth.sso/SAML2/POST, it will automatically be recognized as bound for the new application on that virtual host. All you have to do is ensure that the metadata you provide for the SP includes the necessary endpoints on that virtual host.

In contrast, when you divide things by path, you have to explicitly add XML to the configuration to establish a special handlerURL for the new application, as well as providing the necessary metadata. Typically it might look something like this example. Here, the goal is to establish a separate override for the content inside "/secure/apps/special". In this example the entityID is also being overridden, but that will depend on exactly why you're doing the override.

Example of Path-Based Application Override (shibboleth2.xml)

The big thing to understand is that because of limitations on inheriting settings, you have to supply most of the settings needed in the <Sessions> element because of the need to override the handlerURL. Since one setting is overridden, you have to supply nearly all of them; most of the default properties from the outer <Sessions> element will not be visible to the new application.

Luckily, you do NOT have to actually redefine all of the <Sessions> element's typical child elements. Those will still be inherited, and their locations will be adjusted relative to the new handlerURL you define.

The other key here is to recognize that the handlerURL lives inside the path you set aside for this application to use. It MUST map to the corresponding applicationId, just like any other resources that makes up the application. It's literally part of the application. If you fail to make that connection, you will typically experience looping behavior or errors involving invalid audience conditions, because the SAML assertion delivered to the incorrectly specified handlerURL will be associated with the wrong application and entityID, usually the "default" one.

Using the Override

Configuration

The <ApplicationOverride> element shares nearly all the attributes and elements of the <ApplicationDefault> element.

Getting started

Once you have the additional application defined, you can proceed to define any new settings you need, and correcting the SP's metadata. The metadata can be taken care of first (see the following two sections). Below that, you'll find the precise rules for how settings get inherited, and some example configurations for typical use cases involving application overrides.

Metadata for an Existing SP

If the new application is intended to be "part of" an existing SAML SP that you've established, then you will need to modify the metadata for that SP (keyed by its entityID) to add the additional endpoints that will serve the new application, principally <md:AssertionConsumerService> elements, but possibly others as needed. The location of your new handlers will depend on whether you're using virtual hosts or paths to define the new application (per the previous section).

For a virtual hosting scenario, you should be inheriting a default handlerURL of "/Shibboleth.sso", so the ACS endpoints to add should have Location attributes like "https://myapphost.example.org/Shibboleth.sso/SAML2/POST" and so forth.

For a path-based scenario, you should be defining a custom handlerURL similar to "/myapppath/Shibboleth.sso", so the ACS endpoints to add should have Location attributes like "https://www.example.org/myapppath/Shibboleth.sso/SAML2/POST".

Of course, you'll need to add endpoints for all of the profile and/or protocol bindings you want to support.

Metadata for a New SP

If the application is intended to function as a separate logical SP with its own entityID, then all of the information in the previous section still applies, but of course the endpoints would be found in a new metadata instance (<md:EntityDescriptor>) with the new entityID.

In the majority of cases, it's reasonable (and much simpler) to just reuse the same key pair for the new SP. Since the system is physically the same, there's no real security advantage to creating separate keys apart from perhaps expectation of a future migration of part of the system to a different physical host. In fact, a major advantage of using metadata is to indirect the identity of the SP from the keys that it can use, and it's fine for one key to be acceptable for use by more than one SP.

Inheritance Rules

The precise rules for how each top level <ApplicationDefaults> element is "inherited" when unspecified by a <ApplicationOverride> are specified below. In most cases if an element is NOT supplied at the override level, it will be inherited automatically. 

• <Sessions>

  • If present in the override, most of the default element's attribute content is ignored. Any child elements/handlers defined at the default level WILL apply to the override. If you specify child elements/handlers at the override level, any handlers at a Location used by a default handler will replace the default, while others will supplement the default set. In other words, you can add or replace default handlers, but not disable them.

  • While virtually all of the property/attribute settings at the default level are ignored, the following settings are inherited if not set in the override:

    • redirectLimit

    • redirectAllow (formerly redirectWhitelist) (this is ignored in an override if redirectLimit itself isn't overridden)

• <Errors>

  • If present in the override, the default element's content is ignored.

• <RelyingParty>

• <Notify>

• <MetadataProvider>

• <TrustEngine>

• <AttributeExtractor>

• <AttributeResolver>

• <AttributeFilter>

• <CredentialResolver>

  • These elements are inherited if none are present in the override.

External Overrides

In previous releases, the only way to define an override was to physically add the <ApplicationOverride> child element to the shibboleth2.xml file directly. There is a new feaure that externalizes this. It should be considered somewhat experimental due to a lack of testing to this point but is fully supported.

Instead of an inline definition, one or more search paths can be supplied using <ExternalApplicationOverrides> elements (one path per element), and the system will look for overrides at runtime by appending the string "-override.xml" to the applicationId to attempt to read an XML file by that name in one of the supplied search paths.

The file must contain the entire <ApplicationOverride> element (including appropriate namespace declaration) that would have been placed inside the main file, and the id attribute in the root element must of course match the application ID it's expecting to find in that file. Beyond that, there are no additional security measures, but this can be combined with appropriate file system protections to delegate control over the override's settings to somebody without access to the main configuration.

While this mechanism is somewhat dynamic, it has limitations. The first time the SP is asked to operate with a particular override it hasn't seen before, it will attempt to find the configuration for that override, but after that point it will continue to use those settings until the entire configuration is reloaded or the SP is restarted. The individual override fragments themselves are not reloadable in their own right.

Examples

These examples show how to use the <ApplicationOverride> element to achieve particular goals. The examples don't show the position of the element or the associated changes to achieve the mapping between resources and the new application. You can find examples for that earlier in this topic.

Of course, you can compose these examples as needed.

If you need to use different lifetime/timeout values for sessions with the new application, or are creating a path-based application that needs its own handlerURL, you need to supply a fully populated <Sessions> element. Most of the properties you don't supply will not be inherited, but will get their default documented values (but see above for some exceptions).

As noted earlier, when you supply a custom <Sessions> element, you don't need to repeat all of the child elements that define the handlers unless you want to change them in some way also.

Alternate Sessions Options

If you want to customize the IdP metadata used by an application, you simply provide the desired <MetadataProvider>

Custom Metadata

If you want to customize the SAML attribute handling for an application, you simply provide the desired <AttributeExtractor>

Custom Attribute Mappings

If you want to assign a different private key or certificate to an application, you simply provide the desired <CredentialResolver>.

Custom Credentials