This page shows some sample Shibboleth configurations that leverage the Registered By InCommon Category.

Contents

IdP Uses of the Registered By InCommon Category

Releasing the Essential Attribute Bundle

A Shibboleth IdP uses type basic:ANY to activate a policy for any requester. For example, here's a default attribute release policy that releases the Essential Attribute Bundle to all SPs:

<afp:AttributeFilterPolicy id="releaseEssentialAttributeBundle">

  <!-- this policy is active for ANY requester -->
  <afp:PolicyRequirementRule xsi:type="basic:ANY"/>

  <!-- the Essential Attribute Bundle -->
 
  <afp:AttributeRule attributeID="eduPersonPrincipalName">
    <afp:PermitValueRule xsi:type="basic:ANY"/>
  </afp:AttributeRule>
  <afp:AttributeRule attributeID="email">
    <afp:PermitValueRule xsi:type="basic:ANY"/>
  </afp:AttributeRule>
  <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>

</afp:AttributeFilterPolicy>

A default policy (such as the previous policy) takes on a different meaning in the presence of eduGAIN metadata. For various reasons, some IdPs will want to retain the semantics of their current default policy, at least for a time. This is why the Registered By InCommon Category was created.

Here's how an instance of Shibboleth IdP V2 can leverage the registered-by-incommon entity attribute to retain its current default policy:

<!-- this policy is active for a requester with the following entity attribute -->
<afp:PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
    attributeName="http://macedir.org/entity-category"
    attributeValue="http://id.incommon.org/category/registered-by-incommon"/>

An instance of Shibboleth IdP V3 will either leverage the registered-by-incommon entity attribute (as above) or the <mdrpi:RegistrationInfo> element directly, as shown in the following example:

<!-- this policy is active for a requester whose registrar has the given ID -->
<afp:PolicyRequirementRule xsi:type="saml:RegistrationAuthority"
    registrars="https://incommon.org"/>

The value of the registrars XML attribute above is the globally unique registrar ID for InCommon.

Releasing the R&S Attribute Bundle

Most of the Research & Scholarship (R&S) IdPs in the InCommon Federation are configured with a policy rule that releases attributes to R&S SPs tagged with the legacy InCommon R&S entity attribute value:

<afp:PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
    attributeName="http://macedir.org/entity-category"
    attributeValue="http://id.incommon.org/category/research-and-scholarship"/>
Use of the legacy incommon.org R&S tag to configure attribute release policy at the IdP is deprecated. Eventually this tag will be removed from all SP metadata although a timeline for doing so has not yet been determined.

R&S IdPs should instead be configured with a policy that releases the R&S Attribute Bundle to all R&S SPs, including R&S SPs in other federations:

<afp:AttributeFilterPolicy id="releaseRandSAttributeBundle">

  <!-- for Shib IdP V3, use type saml:EntityAttributeExactMatch instead -->
 
  <afp:PolicyRequirementRule xsi:type="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://refeds.org/category/research-and-scholarship"/>

  <!-- a fixed subset of the Research & Scholarship Attribute Bundle -->
 
  <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>

To facilitate the migration suggested by the previous examples, all R&S SPs registered by InCommon have a multivalued R&S entity attribute in metadata.

It is believed that some R&S IdPs will want to retain their current attribute release policy for a time. An instance of Shibboleth IdP V2 may leverage the Registered By InCommon Category to retain its current attribute release policy but without relying on the legacy InCommon R&S entity attribute value:

<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="saml:AttributeRequesterEntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://id.incommon.org/category/registered-by-incommon"/>
</afp:PolicyRequirementRule>

An instance of Shibboleth IdP V3 will either leverage the registered-by-incommon entity attribute (as above) or the <mdrpi:RegistrationInfo> element directly, as shown in the following example:

<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 more information about configuring an IdP for Research & Scholarship, consult the R&S Attribute Bundle Config topic in the wiki.

SP Uses of the Registered By InCommon Category

Filtering Untrusted Metadata

Add the following MetadataFilter to a MetadataProvider to filter all but InCommon metadata:

<!-- consume only InCommon metadata -->
<MetadataFilter type="Whitelist" matcher="EntityAttributes">
  <saml:Attribute
        Name="http://macedir.org/entity-category"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml:AttributeValue>http://id.incommon.org/category/registered-by-incommon</saml:AttributeValue>
  </saml:Attribute>
</MetadataFilter>

The above policy is sometimes warranted but not always. A more relaxed policy will simply filter the metadata from the discovery interface, as shown in the next section.

Customizing Discovery Interfaces

Here's a complete metadata configuration with a carefully customized discovery interface:

<!--
  The following MetadataProvider refreshes the main InCommon aggregate.
-->
<MetadataProvider type="XML"
    url="http://md.incommon.org/InCommon/InCommon-metadata.xml"
    backingFilePath="InCommon-metadata.xml" maxRefreshDelay="3600">
 
  <!-- Verify the signature on the metadata file -->
  <MetadataFilter type="Signature" certificate="inc-md-cert.pem"/>
 
  <!--
    Require a validUntil XML attribute on the EntitiesDescriptor element
    and make sure its value is no more than 14 days into the future
  -->
  <MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
 
  <!-- Consume all IdP metadata in the aggregate -->
  <MetadataFilter type="EntityRoleWhiteList">
    <RetainedRole>md:IDPSSODescriptor</RetainedRole>
    <RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
  </MetadataFilter>
 
  <!-- Show all IdPs with the registered-by-incommon entity attribute -->
  <DiscoveryFilter type="Whitelist" matcher="EntityAttributes"
      attributeName="http://macedir.org/entity-category"
      attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      attributeValue="http://id.incommon.org/category/registered-by-incommon"/>

  <!-- Hide all IdPs with the hide-from-discovery entity attribute -->
  <DiscoveryFilter type="Blacklist" matcher="EntityAttributes"
      attributeName="http://macedir.org/entity-category"
      attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      attributeValue="http://refeds.org/category/hide-from-discovery"/>
 
</MetadataProvider>

Keep in mind that hiding an IdP from the discovery interface does not prevent the SP from accepting an assertion from that IdP.