Writing an Attribute Release Rule

An attribute release rule specify which values for which attributes are released to which service providers. A collection of attribute release rules are referred to an attribute release policy.

Attribute release rules are specified in the arp.site.xml file.

Writting the Rule

Create a Rule element
Optionally create a Description element, child of the Rule element, whose content is a description of this rule.
Create a Target element, child of the Rule element whose content.
If you want to the rule to apply to any service provider create an AnyTarget element, child of the Target element.
If you want the rule to apply to a specific service provider(s) create a Requester element with the following attribute and whose content is the string to match:
- matchFunction - contains the URI identifier of the function used to evaluate if the content of the Requester element matches the service provider entity ID requesting attributes
Create an Attribute element, child of the Rule element, with the following attribute:
- name - the name of the attribute this rule applies to, this must match the value of the id attribute on the attribute's definition in the resolver.xml configuration file
If you want to all attribute values to be released to the service providers this rule applies to create an AnyValue element, child of the Attribute element
If you want to restrict the values released to the service providers this rule applies to create a Value element, child of the Attribute element with the following attribute and whose content is the string to match:
- matchFunction - contains the URI identifier of the function used to evaluate if the content of the Value element matches the possible value(s) of the attribute
- release - whether to permit the release of the attributes that match this rule or deny them; permissible values "permit" and "deny"

The Rule element must contain exactly one Target element, followed by 0-to-many Attribute elements, followed by 0-to-many AttributeReference elements. Note the ordering: the Target element must apprear before the Attribute elements. More than one Requestor element may appear in a Target element. More than one Value element may appear within an Attribute element.

Match Functions

Match functions determine if a given service provider ID or attribute value match a given criteria. The following match functions ship with Shibboleth.

urn:mace:shibboleth:arp:matchFunction:stringMatch - checks if a service provider ID or attribute value exactly matches the given criteria
urn:mace:shibboleth:arp:matchFunction:stringNotMatch - checks if a service provider ID or attribute value does not exactly matches the given criteria
urn:mace:shibboleth:arp:matchFunction:regexMatch - evaluates a regular expression and indicates a match if the regular expression matches the provider ID or attribute value
urn:mace:shibboleth:arp:matchFunction:regexNotMatch - evaluates a regular expression and indicates a match if the regular expression does not match the provider ID or attribute value
urn:mace:shibboleth:arp:matchFunction:anyValueMatch - matches any non-null string

Example Configuration

This rule releases any value of the eduPersonAffiliation attribute to any service provider

<Rule>
	<Description>eduPersonAffiliation release to anyone</Description>
	<Target>
		<AnyTarget/>
	</Target>

	<Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation">
		<AnyValue release="permit"/>
	</Attribute>
</Rule>

This rule releases most group values, but not administrative ones, to service providers from Brown University

<Rule>
	<Description>Non-adminstrative groups released to Brown</Description>
	<Target>
		<Requester matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch">
			  .*\.brown\.edu.*
		 </Requester>
	 </Target>

	<Attribute name="memberOf">
		<Value release="deny" matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch">
			 ^urn:mace:example.org:group:admin:.*
		 </Value>
	</Attribute>
</Rule>

Advanced Feature: ARP Constraints

New in Shibboleth 1.3.1, ARP Constraints allow the decision to release a given attribute (or group of attributes) to a service provider to be based on the value(s) of other attributes. These constraints were added to address two general use cases:

Complete Suppression of Attribute Release When Not Authorized

In some cases the authorization decision is appropriately made by the Service Provider requiring the release of the attribute payload, while in other cases the Identity Provider is aware of the services a user is authorized for and has either recorded them as entitlements or can derive them from one or more user attributes. Using constraints, an !IdP is able to suppress the unnecessary release of attributes for users that are known to not be authorized for a given service.

Selective Release of Attributes Based on Other Attribute Values

There is often a need to suppress the release of selected attributes based on the values of other attributes. This is particularly necessary in the United States where students can request that certain personal information about them not be released under the Family Educational Rights and Privacy Act (FERPA). This suppression request may be stored in a directory or database as a simple attribute for the user. Using constraints, a policy may be defined in which a Service Provider may receive certain information about all users, and then additional attributes only for those users who have not requested FERPA suppression.

Structure of a Rule Constraint

<Constraint attributeName="attributeDefinitionID"
	matchFunction="urn:functionURN"
	matches="(any|all|none)">value</Constraint>

	Description	Required	Default Value
attributeName	the id of the attribute definition that this constraint value will be matched against	Y
matchFunction	the match function URN that will be used to attempt to match the constraint. All match functions that are defined in Shibboleth are allowed.	N	urn:mace:shibboleth:arp:matchFunction:stringMatch
matches	this can be one of three values (any, all, or none) and describes how many of the attribute values for the given user must match the defined value in order for the constraint to apply	N	any
value	the attribute value to match against. This is required when the specified match function requires an input value. At the time of this writing, the only match function that does not require an input value is "urn:mace:shibboleth:arp:matchFunction:anyValueMatch"	Sometimes

Use Cases and Examples

Complete Suppression of Attribute Release Using Rule Constraint

<AttributeReleasePolicy>
	<Rule>
		<!--Release affiliation only for authorized users -->
		<Constraint attributeName="eduPersonEntitlement">urn:x:foo</Constraint>
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="eduPersonAffiliation">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>
</AttributeReleasePolicy>

Selected Suppression of Attribute Release Based on Other Attribute Values

One common rule and three variant rules are shown. Which of the variants is used depends on how the institution specifies FERPA suppression is in effect. Institutions that populate a FERPA attribute with a specific known value could use either of the first two methods. Institutions that use the mere population of an attribute to indicate FERPA suppression (for example, if the attribute is populated with the date a user requested suppression) would use the third method.

<AttributeReleasePolicy>
	<Rule>
		<!--Release non-sensitive attributes to ServiceX -->
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="eduPersonAffiliation">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>

(method 1, permit release if IsFerpaSuppressed is false)

<!-- method 1 -->
	<Rule>
		<!--Release attrs to ServiceX if IsFerpaSuppressed is false -->
		<Constraint name="myeduIsFerpaSuppressed">false</Constraint>
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="displayName">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>

(method 2, deny release if IsFerpaSuppressed is true)

<!-- method 2 -->
	<Rule>
		<!--Release attrs to ServiceX unless IsFerpaSuppressed is true -->
		<Constraint name="myeduIsFerpaSuppressed" matches="none">true</Constraint>
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="displayName">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>

(method 3, deny release if IsFerpaSuppressed is populated with any value)

<!-- method 3 -->
	<Rule>
		<!--Release attrs to ServiceX unless IsFerpaSuppressed is populated -->
		<Constraint name="myeduIsFerpaSuppressed"
                    matchFunction="urn:mace:shibboleth:arp:matchFunction:anyValueMatch"
                    matches="none" />
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="displayName">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>
</AttributeReleasePolicy>

Use Cases

Rules, Rule Constraints, and Rule Constraint Values can be combined in order to accommodate both simple and complex use cases.

Must have an attribute

Logical expression: P (no specific value)
Example: Release only if user has attribute "foo"
Rule Constraint:

<Constraint name="foo"
	matchFunction="urn:mace:shibboleth:arp:matchFunction:anyValueMatch"
	matches="any" />

Must not have an attribute

Logical expression: not P
Example: Release only if user does not have attribute "foo"
Rule Constraint:

<Constraint name="foo"
	matchFunction="urn:mace:shibboleth:arp:matchFunction:anyValueMatch"
	matches="none" />

Must have a specific attribute value

Logical expression: Px (specific value)
Example: Release only if user has affiliation "member"
Rule Constraint:

<Constraint attributeName="eduPersonAffiliation">member</Constraint>

Must have an attribute value that matches a regular expression

Logical expression: Pe (regular expression)
Example: Release only if user has scoped affiliation matching regular expression .*@example\.edu
Rule Constraint:

<Constraint name="eduPersonScopedAffiliation"
	matchFuntion="urn:mace:shibboleth:arp:matchFunction:regexMatch">.*@example\.edu</Constraint>

Must not have a specific attribute value

Logical expression: not Px
Example: Release only if user does not have affiliation "student"
Rule Constraint:

<Constraint name="eduPersonAffiliation" matches="none">student</Constraint>

Must have at least one of multiple attribute values

Logical expression: Px or Py
Example: Release only if user has affiliation of either "faculty" or "staff"
Rule Constraint:

<Constraint name="eduPersonAffiliation"
	matchFuntion="urn:mace:shibboleth:arp:matchFunction:regexMatch">(faculty|staff)</Constraint>

Must have multiple specific values for the same attribute

Logical expression: Px and Py
Example: Release only if user has both entitlements "urn:x:foo" and "urn:x:bar"
Rule Constraint: (note: multiple constraints are ANDed)

<Constraint name="eduPersonEntitlement">urn:x:foo</Constraint>

<Constraint name="eduPersonEntitlement">urn:x:bar</Constraint>

Must have one specific attribute value, but cannot have another

Logical expression: Px and not Py
Example: Release for all users who have an affiliation of "staff" AND do not have an affiliation of "student" (ie, staff who are not also classified as students)
Rule Constraint: (note: multiple constraints are ANDed)

<Constraint name="eduPersonAffiliation">staff</Constraint>

<Constraint name="eduPersonAffiliation" matches="none">student</Constraint>

Must have an attribute value, but deny a specific one

Logical expression: P and not Px
Example: Release for all users who have an affiliation (any value), unless they have the affiliation "student"
Rule Constraint: (note: multiple constraints are ANDed)

<Constraint name="eduPersonAffiliation" matchFunction="urn:mace:shibboleth:arp:matchFunction:anyValueMatch" />

<Constraint name="eduPersonAffiliation" matches="none">student</Constraint>

Must have specific values for two separate attributes

Logical expression: Px and Qy
Example: Release only if user has entitlement "urn:x:foo" and has affiliation of "faculty"
Rule Constraint: (note: multiple constraints are ANDed)

<Constraint name="eduPersonEntitlement">urn:x:foo</Constraint>

<Constraint name="eduPersonAffiliation">faculty</Constraint>

Must have one attribute value or not a value for another attribute

Logical expression: Px or not Qy

Example: Release for all users who have an affiliation of "staff" or those that do not have isPrivate equal "Y" (ie, release all staff and also release all who are not Private)

This cannot be accomplished within one rule but must be separated into two rules that differ only in the Rule Constraint:

<AttributeReleasePolicy>
	<Rule>
		<!-- First of Two Rules -->
		<Constraint name="eduPersonAffiliation">staff</Constraint>
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="eduPersonAffiliation">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>

	<Rule>
		<!-- Second of Two Rules -->
		<Constraint name="myeduIsPrivate matches="none">Y</Constraint>
		<Target>
			<Requester>https://example.com/shibboleth-sp</Requester>
		</Target>
		<Attribute name="eduPersonAffiliation">
			<AnyValue release="permit" />
		</Attribute>
	</Rule>
</AttributeReleasePolicy>

Potential Caveats

In the existing Shibboleth flow, all authorization decisions occur solely at the Service Provider. With the addition of ARP Constraints, this decision-making may be duplicated at the Identity Provider and therefore could create a problem of keeping these authorization rules synchronized. This proves to be less of a problem if authorization decisions are based on entitlements ? the method of provisioning the entitlement can be modified with no changes to the ARP or AAP.

If a Rule Constraint causes the suppression of all attributes, the Attribute Authority will reply with a completely empty response. The Service Provider will need to ensure that it fails gracefully in this case.