Page Comparison

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.

...

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.

...

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.

...

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.)

<VirtualHost>
...
ServerName myapphost.example.org:443
...
## Note, if you can't apply this globally, you need to make sure
## you apply the setting to both the content/resources *and* to
## the appropriate handler path (generally /Shibboleth.sso).
<Location />
ShibRequestSetting applicationId myappname
</Location>
...
</VirtualHost>

Mapping via the <RequestMap> (shibboleth2.xml)

<RequestMap applicationId="default">
...
    <Host name="myapphost.example.org" applicationId="myappname"/>
...
</RequestMap>

...

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)

<RequestMap applicationId="default">
    <Host name="www.example.org">
        <Path name="secure" requireSession="true">
			<Path name="apps">
				<Path name="special" applicationId="example-special"/>
			</Path>
		</Path>
    </Host>
</RequestMap>
...
<ApplicationDefaults ... entityID="https://www.example.org/shibboleth">
...
    <ApplicationOverride id="myappname" entityId="https://www.example.org/special/shibboleth">
        <Sessions lifetime="28800" timeout="3600" checkAddress="false"
			handlerURL="/secure/apps/special/Shibboleth.sso" />
    </ApplicationOverride>
</ApplicationDefaults>

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.

...

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.

...

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.

...

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.

...

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

<ApplicationOverride id="myappname">
    <Sessions lifetime="28800" timeout="3600"
        handlerURL="/myapppath/Shibboleth.sso" handlerSSL="true"
        cookieProps="; path=/myapppath; secure; HttpOnly"/>
</ApplicationOverride>

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

Custom Metadata

<ApplicationOverride id="myappname">
    <MetadataProvider type="XML" filepath="idpformyapp-metadata.xml"/>
</ApplicationOverride>

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

Custom Attribute Mappings

<ApplicationOverride id="myappname">
    <AttributeExtractor type="XML" filepath="myapp-attribute-map.xml"/>
</ApplicationOverride>

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

Custom Credentials

<ApplicationOverride id="myappname">
    <CredentialResolver type="File" key="myappname-key.pem" certificate="myappname-cert.pem"/>
</ApplicationOverride>

...