Child pages
  • Research and Scholarship Attribute Bundle Config
Skip to end of metadata
Go to start of metadata

To support the Research and Scholarship Category, an IdP has at least two options:

  1. Release the R&S attribute bundle to all R&S SPs, including R&S SPs in other federations
  2. Release the R&S attribute bundle to R&S SPs registered by InCommon only

Visit the parent page for basic info about the R&S Attribute Bundle. See the sections below for detailed configuration instructions.

Other Deployment Options

If your IdP already releases attributes to CILogon (or any other R&S SP), you should convert your CILogon configuration to R&S. More generally, an IdP may choose to release the Essential Attribute Bundle to all SPs. This is easiest to implement and perhaps the best way to support the Research & Scholarship category.

Once you've configured your IdP to release attributes to all R&S SPs (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:

Software Requirements

To release attributes to all R&S SPs with a single configuration, an IdP leverages entity attributes (instead of entity IDs). Thus the configuration steps documented here require Shibboleth IdP v2.3.4 or later, which fully supports using entity attributes in SP metadata as part of an attribute release filter policy.

The configurations based on entity attributes in the following sections are one-time configurations.

Note: The attribute filter policies shown in the following sections are based on an exact match of an entity attribute. In the Shibboleth IdP, an attribute filter policy may be based on a regex match of an entity attribute as well.

Support for Shib IdPs prior to v2.3.4

For Shibboleth IdPs prior to v2.3.4 (which was released on October 27, 2011), InCommon provides an XSLT script that filters InCommon metadata into an explicit <afp:AttributeFilterPolicy> element for R&S SPs. See the Filtering Metadata for Entity Attributes child page.

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

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

Supporting REFEDS R&S

All configuration examples in this section recognize the REFEDS R&S entity attribute value:

http://refeds.org/category/research-and-scholarship

An IdP that supports REFEDS R&S (by recognizing the REFEDS R&S entity attribute) implicitly releases attributes to all R&S SPs, including R&S SPs in other federations. IdPs that are unwilling and/or unable to implement such a policy should consider releasing attributes to R&S SPs registered by InCommon (by recognizing the REFEDS R&S entity attribute in part).

Release a Fixed Subset of the R&S Bundle

The examples in this section show how to configure a Shibboleth IdP to release a fixed subset of the R&S attribute bundle to R&S SPs. A basic policy template is shown below:

<afp:AttributeFilterPolicy id="releaseFixedSubsetRandSBundle">

  <!-- insert the relevant PolicyRequirementRule here -->
  <!-- syntax depends on the version of Shibboleth in use -->

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

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

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

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

  <!-- release of ePSA is OPTIONAL -->
  <afp:AttributeRule attributeID="eduPersonScopedAffiliation">
    <afp:PermitValueRule xsi:type="basic:ANY"/>
  </afp:AttributeRule>

</afp:AttributeFilterPolicy>

For Shib IdPs v3.0.0 and higher

To release a fixed subset of the R&S bundle, configure a new <afp:AttributeFilterPolicy> element that recognizes the R&S entity attribute.

The following example releases a fixed subset of the R&S attribute bundle to all R&S SPs:

<afp:PolicyRequirementRule xsi:type="saml:EntityAttributeExactMatch"
    attributeName="http://macedir.org/entity-category"
    attributeValue="http://refeds.org/category/research-and-scholarship"/>

Note that the above <afp:AttributeFilterPolicy> releases the Research & Scholarship Attribute Bundle to 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 of such configurations, which could easily be incorporated into the above policy.

For Shib IdPs v2.3.4 and higher

Version 2 of the Shibboleth IdP supports a semantically equivalent policy requirement rule but with a slightly different syntax:

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

For brevity, the <afp:AttributeRule> elements have been omitted from the previous configuration element.

Release a Dynamic Subset of the R&S Bundle

To dynamically release a subset of the R&S bundle to each R&S SP on an SP-by-SP basis, configure a new <afp:AttributeFilterPolicy> element that refers to the R&S entity attribute but limits attribute release based on <md:RequestedAttribute> elements in SP metadata.

<afp:AttributeFilterPolicy id="releaseDynamicSubsetRandSBundle">
  
  <!-- insert the relevant PolicyRequirementRule here -->
  <!-- the syntax depends on the version of Shibboleth -->
  
  <!-- release ePPN iff ePPN is listed in metadata -->
  <afp:AttributeRule attributeID="eduPersonPrincipalName">
    <afp:PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
  </afp:AttributeRule>

  <!-- release ePTID iff either ePTID or ePPN are listed in metadata -->
  <afp:AttributeRule attributeID="eduPersonTargetedID">
    <afp:PermitValueRule xsi:type="basic:OR">
      <basic:Rule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
      <basic:Rule xsi:type="saml:AttributeInMetadata"
          attributeName="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"/>
    </afp:PermitValueRule>
  </afp:AttributeRule>

  <!-- if ePPN is non-reassigned, the above rule may be simplified or even commented out since ePTID is optional -->

  <!-- release mail iff mail is listed in metadata -->
  <afp:AttributeRule attributeID="email">
    <afp:PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
  </afp:AttributeRule>

  <!-- release displayName iff displayName or (givenName + sn) are listed in metadata -->
  <afp:AttributeRule attributeID="displayName">
    <afp:PermitValueRule xsi:type="basic:OR">
      <basic:Rule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
      <basic:Rule xsi:type="basic:AND">
        <basic:Rule xsi:type="saml:AttributeInMetadata"
            attributeName="urn:oid:2.5.4.42"/>
        <basic:Rule xsi:type="saml:AttributeInMetadata"
            attributeName="urn:oid:2.5.4.4"/>
      <basic:Rule xsi:type="basic:AND">
    </afp:PermitValueRule>
  </afp:AttributeRule>

  <!-- release givenName iff givenName or displayName are listed in metadata -->
  <afp:AttributeRule attributeID="givenName">
    <afp:PermitValueRule xsi:type="basic:OR">
      <basic:Rule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
      <basic:Rule xsi:type="saml:AttributeInMetadata"
          attributeName="urn:oid:2.16.840.1.113730.3.1.241"/>
    </afp:PermitValueRule>
  </afp:AttributeRule>

  <!-- release surname iff surname or displayName are listed in metadata -->
  <afp:AttributeRule attributeID="surname">
    <afp:PermitValueRule xsi:type="basic:OR">
      <basic:Rule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
      <basic:Rule xsi:type="saml:AttributeInMetadata"
          attributeName="urn:oid:2.16.840.1.113730.3.1.241"/>
    </afp:PermitValueRule>
  </afp:AttributeRule>

  <!-- release ePSA iff ePSA is listed in metadata -->
  <afp:AttributeRule attributeID="eduPersonScopedAffiliation">
    <afp:PermitValueRule xsi:type="saml:AttributeInMetadata" onlyIfRequired="false"/>
  </afp:AttributeRule>

  <!-- since ePSA is OPTIONAL, the above rule may be commented out -->
 
</afp:AttributeFilterPolicy>

See the Shib wiki for more information about type saml:AttributeInMetadata.

For Shib IdPs v3.0.0 and higher

Shib IdP v3.0.0 (and higher) can base policy decisions on arbitrary <md:RequestedAttribute> elements in SP metadata.

The following example releases a dynamic subset of the R&S attribute bundle to all R&S SPs:

<afp:PolicyRequirementRule xsi:type="saml:EntityAttributeExactMatch"
    attributeName="http://macedir.org/entity-category"
    attributeValue="http://refeds.org/category/research-and-scholarship"/>

For Shib IdPs v2.4.3 and higher

Version 2 of the Shib IdP supports an identical policy requirement rule but with a slightly different syntax:

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

For brevity, the <afp:AttributeRule> elements have been omitted from the previous configuration element.

Release the R&S Bundle to R&S SPs Registered By InCommon Only

To release a subset of the R&S attribute bundle to R&S SPs registered by InCommon only, first note that entity metadata registered by InCommon includes the following extension element:

The RegistrationInfo element in InCommon metadata
<md:Extensions xmlns:mdrpi="urn:oasis:names:tc:SAML:metadata:rpi">
  <mdrpi:RegistrationInfo registrationAuthority="https://incommon.org"/>
</md:Extensions>

The value of the registrationAuthority XML attribute is the registrar's ID. Every metadata registrar has a globally unique ID. For example, the InCommon registrar has the ID shown in the previous example, namely, "https://incommon.org".

For Shib IdPs v3.0.0 and higher

Using Shibboleth IdP V3, an IdP operator can choose to restrict attribute release to SPs registered by InCommon as follows:

<afp:PolicyRequirementRule xsi:type="basic:AND">
  <basic:Rule xsi:type="saml:EntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://refeds.org/category/research-and-scholarship"/>
  <basic:Rule xsi:type="saml:RegistrationAuthority"
      registrars="https://incommon.org"/>
</afp:PolicyRequirementRule>

For brevity, the <afp:AttributeRule> elements have been omitted from the previous example. Use a compatible rule set from any of the previous sections.

The registrars XML attribute in the previous example takes a space-separated list of registrar IDs and can therefore be generalized to include other registrars, either in InCommon or in other federations.

The Registered By InCommon Category

A new entity category called the Registered by InCommon Category is being considered. If such a category were implemented, the plugin mentioned in the next example would become unnecessary.

For Shib IdPs prior to v3.0.0

Using a 3rd-party plugin for Shibboleth IdP V2 (developed by the UK federation), an IdP operator can restrict attribute release to SPs registered by InCommon as follows:

<afp:PolicyRequirementRule xsi:type="basic:AND">
  <basic:Rule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://refeds.org/category/research-and-scholarship"/>
  <basic:Rule xsi:type="mdrpif:AttributeRequesterRegistrationAuthority"
      registrars="https://incommon.org"/>
</afp:PolicyRequirementRule>

As above, the <afp:AttributeRule> elements have been omitted from the previous example. Use a compatible rule set from any of the previous sections.

  • No labels