Attribute Release Policies

An Attribute Release Policy (ARP) determines which attributes are released to an Service Provider (SP) when a user tries to access a resource. It acts as a filter on user information contained in the authoritative data sources, deciding what can be released to whom, but not modifying or creating information itself. ARP's can only release attributes that are in a data store that is made available to Shibboleth through the attribute resolver. ARP's are generally administered by the site, but Shibboleth will provide for users to broker control of their own information and privacy by allowing them to create ARP's pertaining to themselves. The SHARPE tool developed by MAMS in Australia is one ARP maintenance tool.

It is recommended that a set of policies be established between an Identity Provider (IdP) and frequently accessed SP's to specify default releases of expected attributes. Federation guidelines may provide more information on population of ARP's.

This section describes how to create ARP's for the default Shibboleth using the XML configuration interface. Care should be given to balancing giving sufficient control over information to users and avoiding access problems. For example, users may decide to restrict the release of their personal information to such a degree that access to a site for a class may become impossible because Shibboleth cannot release enough information to grant access.

ARP Format

Every ARP file contains one ARP. ARP's may be specified either as the site ARP or user ARP's. The site ARP pertains to every principal for whom the Attribute Authority (AA) retrieves information; a user ARP applies only to the individual user for whom it is defined. The set of principals to whom the ARP applies is defined by the name of the ARP file: the site ARP is stored in arp.site.xml and user ARP's are stored as arp.user.$PRINCIPALNAME.xml. Up to two ARP's will apply to a principal: the site ARP, and the user ARP for that principal.

Each ARP acts as a container that holds a set of ARP rules that are applicable to the principals that ARP is effective for. Each ARP rule specifies a single release policy within the ARP container pertaining to a particular application protected by a given SP. For 1.2 or later SP's, this is a single URI matching a providerId. Prior to 1.2, URI's for SP's were not registered. This means that the SHAR name must be used in release policies for 1.1 SP's accessed by users from this IdP. Each ARP rule may contain specifications regarding the release of any number of attribute values to requests matching that ARP rule for that user. ARP rules may be flagged as default, implying that they are always applied to any user matched by the ARP container. ARP's may also be used to restrict specific attribute/value pairs in addition to restricting or releasing individual attributes.

The set of principals that an ARP applies to is not expressed by the ARP itself, but rather the implementation of the ARP repository. For example, if the ARP repository were implemented in LDAP, the ARP's that apply to a user would be attributes of that user's personal LDAP entry, and the site ARP would be an attribute of an entry representing the site. While not performed by the built-in ARP repository, a repository implementation might also implement group ARP's; for example, in an LDAP directory, the user entry might have some group membership attributes that refer to group entries, and those group entries would have ARP attributes, and all those ARP's would be applicable.

The ArpRepository element in idp.xml defines the type of ARP processing and storage to use. The given value specifies Shibboleth's file-based ARP repository implementation, which is currently the only available.

Many example ARP's are provided in their own section.

This element must contain a Path element pointing to the directory containing ARP's to be used by this engine.

ARP Processing

When a query is received, the AA generates an effective ARP, which is the fully evaluated set of ARP rules regarding that relying party based on all ARP containers applicable to the principal. This effective ARP is then applied to attribute values retrieved from the directory and the appropriate assertion is constructed. Default rules are always included in construction of the effective ARP.

• Identify all ARP's that should be applied to a particular principal. This is done by isolating the files in the folder specified by the ArpRepository element that have the name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.
• Find all ARP rules relevant to the query:
  • Any ARP rules within the identified ARP's designated as defaults are automatically included in the effective ARP without performing any matching functions.
  • For each non-default rule in each identified ARP, the matching functions specified in the rule's SP definition are performed. A separate matching function is performed for the requesting SHAR and the providerId on behalf of which the SHAR is making the request.
  • Each matching function evaluates to TRUE if the match is successful or FALSE if it is unsuccessful. If both functions evaluate as TRUE, the rule is included in the Effective ARP.
• Construct the Attribute Filter:
  • For each attribute, compile a temporary list of associated rules that includes all values with a release qualifier of permit.
  • Subtract from this list all attribute values with rules specifying a release qualifier of deny. The resulting list represents the allowable release values for the attribute and is used as a mask for the values which are returned from the Attribute Resolver.
  • If a statement specifies that all values should be permitted, then specific deny qualifiers for specific values should still be enforced. If a statement specifies that all values should be denied, then permit qualifiers for specific values will be ignored.
• Using the mask and attributes returned from the Attribute Resolver, an assertion is constructed.

ARP Syntax

Each ARP is described by an XML file based on a standard .xsd schema. It consists of an AttributeReleasePolicy element referencing the appropriate xsi:schemaLocation and a self-explanatory Description element followed by any number of Rule elements. Each Rule element must consist of a Target element and one or more Attribute elements. The Target element specifies the rules by which the SP definition is formed. The Attribute elements specifies the name and values of the attributes that may be released.

The simplest possible ARP is as follows, which releases eduPersonScopedAffiliation to any SP for the users the ARP applies to:

<?xml version="1.0" encoding="UTF-8"?>
<AttributeReleasePolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns="urn:mace:shibboleth:arp:1.0"
                        xsi:schemaLocation="urn:mace:shibboleth:arp:1.0 shibboleth-arp-1.0.xsd">
    <Description>Simplest possible ARP.</Description>
    <Rule>
        <Target>
           <AnyTarget/>
        </Target>
        <Attribute name="urn:mace:dir:attribute-def:eduPersonAffiliation">
            <AnyValue release="permit"/>
        </Attribute>
    </Rule>
</AttributeReleasePolicy>

All ARP's must take the same basic form. A detailed description of how each element of the Rule element may be sub-populated follows:

Target: Target may contain either the AnyTarget element, which will cause the Target to always return TRUE , or both the Requester element, which provides for matches to be performed against the SHAR name for 1.1 SP's or the providerId for 1.2 or later SP's, and the Resource element, which provides for matches to be performed against the requested URL.

When going against 1.1 SP's, the Resource element will refer to individual URL trees protected by a given SHAR. However, due to the nature of application identifiers, the Resource element has no meaning when releasing to 1.2 or later SP's. These will always function as though <AnyResource/> is specified, making the entire Resource element necessary only if this IdP will be applying this ARP to 1.1 SP's.

There are three matches that may be performed by the AA in evaluating ARP's by using the matchFunction component of the Requester and Resource elements. The following match patterns may be specified directly following the Requester or Resource elements, such as:

<Requester matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch">

• urn:mace:shibboleth:arp:matchFunction:exactShar: May be used with the Requester element. Evaluates to TRUE when the string content of the Requester element matches exactly the providerId of the requesting application of 1.2 or later SP's or the SHAR name of 1.1 SP's. Otherwise evaluates to FALSE . Serves as the default value associated with Requester if none is specified.
• urn:mace:shibboleth:arp:matchFunction:resourceTree: May be used with the Resource element. However, this has no meaning when releasing to 1.2 or later SP's. Evaluates to TRUE when the location of the resource either matches exactly or begins with the string content of the Resource element. Otherwise evaluates to FALSE .

• urn:mace:shibboleth:arp:matchFunction:regexMatch: May be used with both the Requester and Resource elements. Evaluates to TRUE when the providerId of a request for 1.2 or later SP's or the name of the requesting SHAR for or the requested URL tree for 1.1 SP's is a valid match of the regular expression represented as the content of the containing element. Otherwise evaluates to FALSE . Regular expressions are evaluated in accordance with the Java 1.4 Pattern API.

Attribute: The Attribute element must always specify the URN of the attribute whose release parameters it specifies. Additionally, it must contain either the AnyValue element or one or more Value elements. These elements, in turn, must specify either permit , or deny . The Value element must then contain one value for which the rule applies. Some examples follow:

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName">
    <AnyValue release="Permit"/>
</Attribute>

Permits the release of eduPersonPrincipalName with any value.

<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
    <Value release="deny">member@example.edu</Value>
</Attribute>

Forcibly denies the release of eduPersonScopedAffiliation value member@example.edu . Other values of the attribute may still be released if so specified by a permit ARP.