Hide From Discovery Category

The "Hide From Discovery" entity category is a category of Identity Providers that are intended not to be shown on discovery interfaces by default.

The hide-from-discovery entity attribute is self-asserted by IdP operators but InCommon Operations may insert the hide-from-discovery entity attribute into any IdP entity descriptor at its discretion.

Contents

Motivation

By and large, participants register an IdP for one or more of the following reasons:

1. To interoperate with providers of commercial vendor services called Sponsored Partners
2. To interoperate with Enterprise Services (co-located in the same security domain as the IdP)
3. To interoperate with cross-domain Federation Services such as Research & Scholarship Category services and other collaborative services

To interoperate with Sponsored Partners and Enterprise Services, a bilateral arrangement is often needed, whereas cross-domain Federation Services are "promiscuous" in the sense that they are willing and able to interoperate with any IdP. This gives rise to IdP Discovery, a user-driven process (or interface) to discover the federated user's preferred IdP.

An IdP that interoperates solely with Sponsored Partners and/or Enterprise Services may not need (or want) to be exposed on arbitrary discovery interfaces, in which case the IdP should declare the hide-from-discovery entity attribute in metadata. Federation Services can (and should) filter such IdPs from their discovery interfaces.

Discoverable IdPs

A discoverable IdP has the following highly desirable characteristics:

1. Consumes the metadata of all SPs
   
   1. A discoverable IdP will automatically refresh InCommon metadata at least daily
2. Responds to all authentication requests
   
   1. A discoverable IdP supports SAML2 Web Browser SSO and always issues a SAML assertion in response to a SAML2 AuthnRequest
3. Publishes the following user interface elements in metadata:
   
   1. DisplayName
   2. Description (optional)
   3. Information URL (optional)
   4. Logo URL (optional)
4. Publishes a favicon on the IdP server
5. Publishes an appropriate error handling URL in metadata

For example, a Federation Site Administrator should log into the Federation Manager and self-assert the hide-from-discovery entity attribute in IdP metadata if any of the following are true:

1. Your IdP does not automatically refresh InCommon metadata at least daily

2. Your IdP deployment is based on software other than Shibboleth or simpleSAMLphp (since these are the only SAML implementations known to be able to refresh metadata)

3. Your IdP filters SP metadata in any way

4. Your IdP is configured primarily for vendor SPs and therefore not intended for federated transactions with arbitrary SPs

5. Your IdP does not publish a SAML2 SingleSignOnService endpoint that supports the HTTP-Redirect binding

6. An authentic user presents an arbitrary SAML2 AuthnRequest to your IdP but your IdP is unable or unwilling to respond to the request

7. You publish the metadata of a test IdP with an obfuscated DisplayName (such as “zTest_My University Test IdP”) that competes with the DisplayName of your production IdP (“My University IdP”)

8. Your error handling URL in metadata is missing, broken, or points to a page that does not contain sufficient information for users with questions about attribute release

Entity Attribute

An IdP calls out its desire to Hide From Discovery by asserting the following entity attribute in metadata (whitespace added for readability):

<mdattr:EntityAttributes
    xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
  <saml:Attribute
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      Name="http://macedir.org/entity-category">
    <saml:AttributeValue>
      http://refeds.org/category/hide-from-discovery
    </saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>

To assert the hide-from-discovery entity attribute in IdP metadata, a Site Administrator logs into the Federation Manager, clicks the "Identity Provider Metadata Wizard," and opts into the Hide From Discovery Category by clicking the appropriate checkbox. See the FM Change Log for a snapshot of the Hide From Discovery user interface.

Note: InCommon Operations may insert the above entity attribute into any IdP entity descriptor at its discretion. This may happen, for instance, if the IdP is experiencing an extended period of technical difficulties.

Configure the Shibboleth SP

To configure Shibboleth SP 2.5 (and later) to download and verify signed InCommon metadata every hour, and to filter on the Hide From Discovery entity attribute, do the following:

<!--
  The following MetadataProvider refreshes the InCommon production metadata aggregate
  but filters on the hide-from-discovery entity attribute.
-->
<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>

  <!-- Hide all IdPs with the hide-from-discovery entity attribute. -->
  <!-- (Hiding an IdP from the discovery interface does NOT prevent -->
  <!-- the SP from accepting an assertion from the IdP.) -->
  <DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true"
      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>

Compare the above MetadataProvider with a typical Shibboleth Metadata Config.

For More Information

• https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider