The Incommon Federation wiki has moved.

Please visit the new InCommon Federation Library wiki for updated content. Remember to update your bookmarks.

Click in the link above if you are not automatically redirected in 15 seconds.



You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 56 Next »

Shibboleth Metadata Configuration

The Shibboleth software will not only consume metadata, it will also fetch and verify a fresh metadata file on a regular basis. Later versions of Shibboleth are highly optimized with respect to metadata refresh.

Contents

The following examples fetch the main InCommon production metadata aggregate. See the Metadata Aggregates wiki page for other options.

Before you can verify the XML signature on a metadata aggregate, you need an authentic copy of the InCommon Metadata Signing Certificate. Do this first, before configuring Shibboleth for metadata refresh.

Configure the Shibboleth IdP

Protect Against Failed Metadata Processes

The Shibboleth IdP is known to be sensitive to large metadata aggregates. To protect against failed metadata processes, InCommon recommends that deployers allocate at least 1500MB of heap space in the JVM. Do this for all your Shibboleth IdP deployments, in both test and production, for both V3 and V2.

Configure Shibboleth IdP V3

To configure Shibboleth IdP 3.2.0 (and later) to download and verify signed InCommon metadata every hour, do the following:

Configure Shibboleth IdP 3.2.0 (and later)
<!-- 
  Use a ChainingMetadataProvider in case you want to nest other metadata providers later on 
-->
<MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider"
                  xmlns="urn:mace:shibboleth:2.0:metadata">

  <!--
    Refresh the InCommon production metadata aggregate every hour.
 
    Note: The defaults for minRefreshDelay, maxRefreshDelay, and refreshDelayFactor
    are "PT5M", "PT4H", and "0.75", respectively. The value of maxRefreshDelay
    has been modified below such that the metadata is refreshed every hour ("PT1H").
    The other properties merely regurgitate their default values. They are included
    here for convenience, in case you want to change their default values.
  -->
  <MetadataProvider id="ICMD" xsi:type="FileBackedHTTPMetadataProvider"
                    xmlns="urn:mace:shibboleth:2.0:metadata"
                    metadataURL="http://md.incommon.org/InCommon/InCommon-metadata.xml"
                    backingFile="%{idp.home}/metadata/InCommon-metadata.xml"
                    minRefreshDelay="PT5M"
                    maxRefreshDelay="PT1H"
                    refreshDelayFactor="0.75">

      <!--
        To bootstrap the trust fabric of the federation, each relying party 
        obtains and configures an authentic copy of the federation operator’s 
        Metadata Signing Certificate (https://spaces.at.internet2.edu/x/moHFAg).
 
        Fetch the InCommon Metadata Signing Certificate and check its integrity:
 
        $ IDP_HOME=/opt/shibboleth-idp
        $ /usr/bin/curl --silent https://ds.incommon.org/certs/inc-md-cert.pem \
            | /usr/bin/tee $IDP_HOME/credentials/inc-md-cert.pem \
            | /usr/bin/openssl x509 -sha1 -fingerprint -noout
        SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD
 
        Verify the signature on the root element of the metadata aggregate 
        (i.e., the EntitiesDescriptor element) using the trusted Metadata 
        Signing Certificate.
      -->
      <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
              certificateFile="%{idp.home}/credentials/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 xsi:type="RequiredValidUntil" maxValidityInterval="P14D" />

      <!-- Consume all SP metadata in the aggregate -->
      <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
      </MetadataFilter>

  </MetadataProvider>

</MetadataProvider>

Configure Shibboleth IdP V2

To configure Shibboleth IdP 2.2 (and later) to download and verify signed InCommon metadata every hour, do the following:

Configure Shibboleth IdP 2.2 (and later)
<!-- Chaining metadata provider defined in the default IdP relying-party configuration file -->
<MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider"
                  xmlns="urn:mace:shibboleth:2.0:metadata">

  <!--
    Refresh the InCommon production metadata aggregate every hour.
 
    Note: The defaults for minRefreshDelay, maxRefreshDelay, and refreshDelayFactor
    are "PT5M", "PT4H", and "0.75", respectively. The default for maxRefreshDelay
    has been modified below such that the metadata is refreshed every hour ("PT1H").
    The other properties merely regurgitate their default values. They are included
    here for convenience, in case you want to change their default values.
  -->
  <MetadataProvider id="ICMD" xsi:type="FileBackedHTTPMetadataProvider"
                    xmlns="urn:mace:shibboleth:2.0:metadata"
                    metadataURL="http://md.incommon.org/InCommon/InCommon-metadata.xml"
                    backingFile="/opt/shibboleth-idp/metadata/InCommon-metadata.xml"
                    minRefreshDelay="PT5M"
                    maxRefreshDelay="PT1H"
                    refreshDelayFactor="0.75">

    <!-- Use a chaining filter to allow multiple filters to be added -->
    <MetadataFilter xsi:type="ChainingFilter">

        <!--
          Require the metadata to be signed and use the trust engine
          labeled id="ICTrust" to determine its trustworthiness
        -->
        <MetadataFilter xsi:type="SignatureValidation" 
                        trustEngineRef="ICTrust" requireSignedMetadata="true" />

        <!--
          Require a validUntil XML attribute on the EntitiesDescriptor element
          and make sure its value is no more than 14 days into the future 
        -->
        <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D" />

        <!-- Consume all SP metadata in the aggregate -->
        <MetadataFilter xsi:type="EntityRoleWhiteList">
          <RetainedRole>samlmd:SPSSODescriptor</RetainedRole>
        </MetadataFilter>

    </MetadataFilter>
  </MetadataProvider>

</MetadataProvider>

<!--
  This TrustEngine (beneath the Security Configuration section) is an 
  implementation of the Explicit Key Trust Model (https://spaces.at.internet2.edu/x/t43NAQ).
 
  To bootstrap the trust fabric of the federation, each relying party 
  obtains and configures an authentic copy of the federation operator’s 
  Metadata Signing Certificate (https://spaces.at.internet2.edu/x/moHFAg).
 
  Fetch the InCommon metadata signing certificate and check its integrity:
 
  $ /usr/bin/curl --silent https://ds.incommon.org/certs/inc-md-cert.pem \
      | /usr/bin/tee /opt/shibboleth-idp/credentials/inc-md-cert.pem \
      | /usr/bin/openssl x509 -sha1 -noout -fingerprint
  SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD
-->
<security:TrustEngine id="ICTrust" xsi:type="security:StaticExplicitKeySignature">

  <security:Credential id="MyFederation1Credentials" xsi:type="security:X509Filesystem">
    <security:Certificate>/opt/shibboleth-idp/credentials/inc-md-cert.pem</security:Certificate>
  </security:Credential>
</security:TrustEngine>

Configure the Shibboleth SP

To configure Shibboleth SP 2.5 (and later) to download and verify signed InCommon metadata every hour, do the following:

Configure Shibboleth SP 2.5 (and later)
<!--
  The following MetadataProvider attempts to refresh the main InCommon metadata 
  aggregate every hour. It also hides all IdPs with the hide-from-discovery 
  entity attribute.
-->
<MetadataProvider type="XML" 
    url="http://md.incommon.org/InCommon/InCommon-metadata.xml"
    backingFilePath="InCommon-metadata.xml" maxRefreshDelay="3600">

  <!--
    To bootstrap the trust fabric of the federation, each relying party 
    obtains and configures an authentic copy of the federation operator’s 
    Metadata Signing Certificate (https://spaces.at.internet2.edu/x/moHFAg).
 
    Fetch the InCommon Metadata Signing Certificate and check its integrity:
 
    $ /usr/bin/curl --silent https://ds.incommon.org/certs/inc-md-cert.pem \
        | /usr/bin/tee inc-md-cert.pem \
        | /usr/bin/openssl x509 -sha1 -fingerprint -noout
    SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD
 
    Verify the signature on the root element of the metadata aggregate 
    (i.e., the EntitiesDescriptor element) using the trusted Metadata 
    Signing Certificate.
  -->
  <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. -->
  <!-- This filter has no effect if your app has no discovery interface. -->
  <!-- Note: 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>

Slow network connection?

If you routinely experience network issues while refreshing InCommon metadata, try increasing the timeout on the SP's metadata refresh process. For example, the following child element of the above <MetadataProvider> parent element sets the transport timeout to 120 seconds:

<TransportOption provider="CURL" option="13">120</TransportOption>

See the NativeSPTransportOption topic in the Shibboleth wiki for more details.

For More Information

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels