Page History

Once you've configured your IdP, you can test your configuration using this test page, a service provided by the GENI Experimenter Portal, an official R&S SP.

<!-- for Shibboleth IdP V3.2.0 or later -->
 
<AttributeFilterPolicy id="releaseRandSAttributeBundle">
 |https://docs.google.com/a/internet2.edu/spreadsheet/viewform?formkey=dDBabVBYNXo5a0tHRTRHOFJJMUQ0dGc6MQ#gid=0] now!{note}{div}

To support the [Research and Scholarship Category], an IdP has multiple options:

# Release the [essential attribute bundle|Essential Attribute Bundle] to all SPs (this policy is *easiest to implement*)
# Release the [R&S attribute bundle|Research and Scholarship Attribute Bundle] to all R&S SPs
# Release a [minimal subset of the R&S attribute bundle|Research and Scholarship Attribute Bundle#minimal-subset] to all R&S SPs
# Release a dynamic subset of the R&S attribute bundle to each R&S SP on an SP-by-SP basis

See the sections below for detailed instructions.

{tip:title=Other Deployment Options}
If your IdP already releases attributes to [CILogon|https://cilogon.org] (which is an R&S SP), you should [convert your CILogon configuration to R&S|Convert a CILogon Config to R and S]. More generally, an IdP may choose to release the [Essential Attribute Bundle] to *all SPs*.
{tip}

Once you've configured your IdP to release attributes to [all R&S SPs|https://incommon.org/federation/info/all-sp-categories.html] (both present and future) as described below, you should optimize your IdP configuration files by removing all references to the entity IDs of individual R&S SPs. (That is, in fact, the whole point of using entity attributes to configure attribute release policy.)

*Contents*:

{toc:minLevel=2}

{anchor:software-reqs}

h2. Software Requirements

To release attributes to [all R&S SPs|https://incommon.org/federation/info/all-sp-categories.html] with a single configuration, an IdP leverages [entity attributes|Entity Attributes] (instead of [entity IDs|Entity IDs]). Thus the configuration steps documented here require Shibboleth IdP&nbsp;v2.3.4 or later, which fully supports using entity attributes in SP metadata as part of an attribute release filter policy.

_Note_: The attribute filter policies shown in the following sections are based on an [exact match of an entity attribute|https://wiki.shibboleth.net/confluence/x/vYBX]. In the Shibboleth IdP, an attribute filter policy may be based on a [regex match of an entity attribute|https://wiki.shibboleth.net/confluence/x/wYBX] as well.

{info:title=Support for Shib IdPs prior to v2.3.4}
For Shibboleth IdPs prior to v2.3.4 (which was released on October&nbsp;27, 2011), InCommon provides an [XSLT script|Research and Scholarship Attribute Bundle Config^InCommonRandSPolicy.xsl] that filters InCommon metadata into an explicit {{<AttributeFilterPolicy>}} element for R&S SPs. See the next section for specific [instructions for old IdPs|#oldIdPs].
{info}

No other SAML IdP software is known to support entity attributes at this time.

h2. Release the R&S Bundle to All R&S SPs

An IdP supports R&S by releasing the [R&S attribute bundle|Research and Scholarship Attribute Bundle] to all R&S SPs. Both of the examples in this section illustrate such a configuration.

The configuration based on entity attributes in the next subsection is a one-time operation. In contrast, the configuration produced by the XSLT script in the following subsection must be performed every time a new R&S SP is added to InCommon metadata. Clearly the configuration based on entity attributes is preferred.

{anchor:newIdPs}
h3. For Shib IdPs v2.3.4 and higher

To release a fixed subset of the [R&S bundle|Research and Scholarship Category#Attribute_Bundle] (or the complete bundle itself), configure a new {{<AttributeFilterPolicy>}} element that refers to the [R&S entity attribute|Research and Scholarship Entity Metadata]. The following example releases the full R&S bundle to all R&S SPs:

{code:xml}
<AttributeFilterPolicy id="releaseFullBundleToRandS">

  <PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatchEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://id.incommonrefeds.org/category/research-and-scholarship"/>

  <!-- <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="eduPersonTargetedID">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="eduPersonScopedAffiliation">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

</AttributeFilterPolicy>
{code}

Note that the above {{<AttributeFilterPolicy>}} releases the [a fixed subset of the Research & Scholarship Attribute Bundle|Research and Scholarship Attribute Bundle] for *all* users whereas an IdP that supports R&S is only required to release attributes for _some subset of the IdP's user population_. For example, an IdP may choose to release attributes for faculty and staff only, or perhaps for non-students. The Shibboleth wiki contains [examples|https://wiki.shibboleth.net/confluence/x/84BC] of such configurations, which could easily be incorporated into the above {{<AttributeFilterPolicy>}} element.

{anchor:oldIdPs}
h3. For Shib IdPs prior to v2.3.4

Old versions of the Shib IdP don't support [entity attributes|Entity Attributes] so we provide an XSLT script that extracts the entity IDs of the R&S SPs. Run the script ({{InCommonRandSPolicy.xsl}}) at the command line as follows:

{html}<pre>
$ <b>curl --silent http://md.incommon.org/InCommon/InCommon-metadata.xml \
    | xsltproc InCommonRandSPolicy.xsl - \
    | tidy -quiet -xml -indent -wrap 0</b>
</pre>{html}

The output will include a listing of the entity IDs of *all* R&S SPs found in the metadata file:

{code:xml}
<AttributeFilterPolicy id="releaseFullBundleToRandS">

  <PolicyRequirementRule xsi:type="basic:OR">
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://carmenwiki.osu.edu/shibboleth" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://filesender.internet2.edu/shibboleth" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://wikispaces.psu.edu/shibboleth" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://www.indianactsi.org" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://cilogon.org/shibboleth" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://cgca.phys.uwm.edu/shibboleth-sp" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://panther.gpolab.bbn.com/shibboleth" />
    <basic:Rule xsi:type="basic:AttributeRequesterString" value="https://ligo.org/ligovirgo/cbcnote/shibboleth-sp" />
    <!-- etc. -->
  </PolicyRequirementRule>

  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="eduPersonTargetedID">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="eduPersonScopedAffiliation">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

</AttributeFilterPolicy>
{code}

You can of course modify either of the above {{<AttributeFilterPolicy>}} elements to release a minimal subset of the R&S attribute bundle as shown in the following section.

h2. Release a Minimal Subset of the R&S Bundle to All R&S SPs

The following example for Shib IdP&nbsp;v2.3.4 (and higher) releases a [minimal subset of the R&S attribute bundle|Research and Scholarship Attribute Bundle#minimal-subset] to all R&S SPs:

{code:xml}
<AttributeFilterPolicy id="releaseMinimalSubsetToRandS">

  <PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://id.incommon.org/category/research-and-scholarship"/>

>
 
  <!-- release of ePPN is REQUIRED -->
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

  <!-- if your deployment of ePPN is non-reassigned, release of ePTID is OPTIONAL -->
  <AttributeRule attributeID="eduPersonTargetedID">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

  <!-- eitherrelease displayName or (givenName and sn) of email is REQUIRED but all three are RECOMMENDED -->
  <AttributeRule attributeID="displayNameemail">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="basic:ANY"/>
  </AttributeRule>

</AttributeFilterPolicy>
{code}

Note that the above policy may be trimmed further as indicated in the XML comments.

h2. Release a Dynamic Subset of the R&S Bundle to All R&S SPs

To dynamically release a subset of the [R&S bundle|Research and Scholarship Category#Attribute_Bundle] to each R&S SP on an SP-by-SP basis, configure a new {{<AttributeFilterPolicy>}} element that refers to the [R&S entity attribute|Research and Scholarship Entity Metadata] but limits attribute release to only those {{<md:RequestedAttribute>}} elements in SP metadata. 

{warning}
Both policies shown below satisfy the requirements of R&S if and only if 1)&nbsp;your deployment of {{eduPersonPrincipalName}} is non-reassigned, and 2)&nbsp;your deployment supports all three person name attributes ({{displayName}}, {{givenName}}, and {{surname}}).
{warning}

h3. For Shib IdPs v2.4.0 and higher

Shib IdP v2.4.0 (and higher) can base policy decisions on {{<md:RequestedAttribute>}} elements in SP metadata. For example, the following configuration releases an R&S attribute from the minimal subset if and only if that attribute is called out in SP metadata:

{code:xml}
<AttributeFilterPolicy id="releaseDynamicSubsetToRandS">
 
  <PolicyRequirementRule
      xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://id.incommon.org/category/research-and-scholarship"/>
 
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="<!-- either displayName or (givenName and sn) is REQUIRED but all three are RECOMMENDED -->
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="falseANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="falseANY"/>
  </AttributeRule>

</AttributeFilterPolicy>
{code}

See the Shib wiki for more information about type [{{saml:AttributeInMetadata}}|https://wiki.shibboleth.net/confluence/display/SHIB2/IdPFilterRequirementAttributeInMetadata].

h3. For Shib IdPs prior to 2.4.0

{info:title=Support for Shib IdPs prior to v2.3.4}
The sample policy in this subsection is based on entity attributes, so the Shib IdP is assumed to be at least v2.3.4. For Shib IdPs prior to v2.3.4, it is possible to combine the use of the third-party plugin documented below with the XSLT script show above, but we do not show such an example here.
{info}

Shib IdPs prior to v2.4.0 are not able to natively process {{<md:RequestedAttribute>}} elements in SP metadata so here we show how to install and configure a third-party plugin that adds this capability. The following two-step configuration process is required:

# Install and configure a general-purpose plugin that limits attribute release to the {{<md:RequestedAttribute>}} elements in SP metadata.
# Configure a new {{<AttributeFilterPolicy>}} element for R&S SPs.

These two configuration steps taken together constrain the release of attributes to precisely those attributes requested by R&S SPs (assuming those attributes constitute a subset of the R&S bundle).

h4. Install and Configure the Plugin

The [uApprove|http://www.switch.ch/aai/support/tools/uApprove.html] addon to the Shibboleth IdP includes a plugin that limits attribute release to the {{<md:RequestedAttribute>}} elements in SP metadata.

{info:title=uApprove}
The complete uApprove addon is *not* required to release attributes to R&S SPs. The steps below do *not* install uApprove but rather a plugin included in the uApprove package.
{info}

To install and configure the plugin, perform the following steps:

# Download and unpack the [uApprove|http://www.switch.ch/aai/support/tools/uApprove.html] package
# Copy the IdP plugin to your IdP build directory:
{html}<code>$ <b>cp $UAPPROVE_INSTALL$/idp-plugin-2.2.1/lib/* $IDP_INSTALL$/lib/</b></code>{html}
# Rebuild the IdP
# Add the namespace declaration {{xmlns:ua="http://www.switch.ch/aai/idp/uApprove/mf"}} to the {{<AttributeFilterPolicy>}} element (or better yet, to the parent {{<AttributeFilterPolicyGroup>}} element).
# Append the following values to the whitespace delimited list of values for the {{xsi:schemaLocation}} attribute:
{{{nl:http://www.switch.ch/aai/idp/uApprove/mf} classpath:/schema/uApprove-mf.xsd}}

The plugin adds a new {{PermitValueRule}} of type {{ua:AttributeInMetadata}}.

h4. Configure a New AttributeFilterPolicy

The following IdP configuration implicitly releases attributes to _any_ R&S SP. An attribute is released if and only if it is listed in SP metadata.

{code:xml}
<AttributeFilterPolicy id="releaseToRandS" xmlns:ua="http://www.switch.ch/aai/idp/uApprove/mf">

  <PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://id.incommon.org/category/research-and-scholarship"/>
 <!-- release of ePSA is OPTIONAL -->
  <AttributeRule attributeID="eduPersonPrincipalNameeduPersonScopedAffiliation">
    <PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="ua:AttributeInMetadata" onlyIfRequired="false"ANY"/>
  </AttributeRule>

</AttributeFilterPolicy>
{code}

The attributes shown above constitute a minimal subset of the R&S bundle. Simply customize the above example to match your policy.

{attachments}