ArpConstraint

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.