RelyingPartyConfiguration

File(s): conf/relying-party.xml, conf/idp.properties
Format: Native Spring

1 Overview
2 General Configuration
3 Overrides
- 3.1 Examples
- 3.2 Multiple Overrides
4 Profile Configuration
5 Reference

Overview

The relying-party.xml file is used to specify the functional features (SAML and otherwise) you want the IdP to support (these are termed "profiles"), and to customize IdP or profile settings based on the identity, or a few other characteristics, of a relying party service.

You can modify this file to:

control which profiles are supported for particular partners (or for anonymous requests)
alter default profile or global settings
define and attach custom security configurations at various levels, such as:
- turning off encryption of assertions and other content
- changing which layer signing is performed (responses vs. assertions)
- supporting multiple signing credentials
- customizing algorithms

The goal of any deployment is to reduce the number of customizations used, so the ideal is to rarely have to modify this configuration. Further, there are more modern techniques that allow many or most uses of this file to be replaced by MetadataDrivenConfiguration; that is, instead of creating explicit rules in this file, it's usually cleaner in the long run to add information to SP metadata to effect the change desired. Over time, it becomes easier to get a feel for when it's easier to use metadata and when it's easier to use overrides.

General Configuration

While the native Spring syntax can ultimately be used to wire up any beans you choose to define, we have abstracted this to some degree by making use of conventions, parent beans, and pre-defined bean names to limit the amount of XML needed to make useful changes.

The absolute rule is that the file MUST contain three named beans:

shibboleth.UnverifiedRelyingParty
shibboleth.DefaultRelyingParty
shibboleth.RelyingPartyOverrides

All three are defined for you by default.

The first two must define beans that derive from the RelyingPartyConfiguration class, but this is automatically done by inheriting (via the parent attribute) from the bean named RelyingParty.

The "unverified" RP bean controls how to handle requests from peers with no metadata or other mechanism in place to authenticate/verify the request. By default, no profiles are enabled, signified by the empty profileConfigurations list.

The "default" RP bean applies to requests from peers that do not fit the conditions attached to any overrides, and are thus handled with default settings. By default, this relies on a variety of built-in settings, and activates a number of the usual profiles, though the exact list may vary over time with particular releases (things that used to be common may become rare).

The last bean is a List<RelyingPartyConfiguration> for any overrides. Those beans will generally be of special types that determine their applicability, or will generically contain an activationCondition property that determines whether one applies to a request or not.

The first applicable override bean is used, and there is no merging of settings between any of the beans.

Overrides

Overrides allow for arbitrary conditions to be evaluated to assign behavior to a request. In the general case these conditions can be complex scripts or Java code.

To simplify this in the most common scenarios, we have included additional parent beans that can be inherited from to more easily express these conditions. Right now, we have these built-in helpers:

RelyingPartyByName
RelyingPartyByGroup
RelyingPartyByEntitiesDescriptor
RelyingPartyByTag
RelyingPartyByMappedTag

Examples

<!-- Example matching one SP -->
<bean parent="RelyingPartyByName" c:relyingPartyIds="https://sp.example.org/sp">
    <property name="profileConfigurations">
        <list>
		<!-- Your refs or beans here. -->
        </list>
    </property>
</bean>

<!-- Example matching two SPs -->
<bean parent="RelyingPartyByName" c:relyingPartyIds="#{{'https://sp.example.org/sp', 'https://another.example.org/sp'}}">
    <property name="profileConfigurations">
        <list>
		<!-- Your refs or beans here. -->
        </list>
    </property>
</bean>

<!-- Example matching three (or more) SPs -->
<bean parent="RelyingPartyByName">
	<constructor-arg name="relyingPartyIds">
		<list>
			<value>https://sp.example.org/sp</value>
			<value>https://another.example.org/sp</value>
			<value>https://still.another.example.org/sp</value>
		</list>
	</constructor-arg>
    <property name="profileConfigurations">
        <list>
		<!-- Your refs or beans here. -->
        </list>
    </property>
</bean

(Note that the second example above uses a Spring Expression Language inline list. This can get arbitrarily long, so the third example shows this in a more readable syntax for longer lists.)

The following example notwithstanding, it's not advisable to create policy based on groups because those hierarchies are very dependent on metadata aggregation and publishing approaches that are much less common today.

<bean parent="RelyingPartyByGroup" c:groupNames="urn:mace:incommon">
	<property name="profileConfigurations">
		<list>
		<!-- Your refs or beans here. -->
		</list>
	</property>
</bean>

There is also support for group matching based on a SAML metadata feature called an <AffiliationDescriptor>, and you are able to create locally (or even remotely) expressed group memberships using that technique, by supplying supplemental metadata to the system. If you want to optimize by ignoring the possibility of <AffiliationDescriptor> use, the RelyingPartyByEntitiesDescriptor bean will bypass that step and suppress some logging that shows up during the affiliation lookup.

An alternative grouping strategy is based on <EntityAttributes> metadata extension tags. The tag-based approach is a generally recommended way of doing simple overrides that might apply to a large number of systems, and is a bridge between the "explicit" syntax and the more generic MetadataDrivenConfiguration approach.

<bean parent="RelyingPartyByTag">
	<constructor-arg name="candidates">
		<list>
			<bean parent="TagCandidate" c:name="http://macedir.org/entity-category"
				p:values="http://refeds.org/category/research-and-scholarship"/>
		</list>
	</constructor-arg>
	<property name="profileConfigurations">
		<list>
		<!-- Your refs or beans here. -->
		</list>
	</property>