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 The Shibboleth software is highly optimized with respect to metadata refresh.The following examples fetch the main InCommon production metadata aggregate. See the Metadata Aggregates wiki page for other options.
Contents
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
To configure Shibboleth IdP 3.0 (and later) to download and verify signed InCommon metadata every hour, do the following:
The IdP configuration examples in this section fetch the main InCommon production metadata aggregate. See the Metadata Aggregates wiki page for other options.
Warning |
---|
title | 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 download and verify signed InCommon metadata every hour, configure Shibboleth IdP 3.2.0 (and later) as follows:
Code Block |
---|
language | xml |
---|
title | Configure Shibboleth IdP 3.2.0 (and later) |
---|
collapse | true |
---|
|
<!--
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 |
Code Block |
---|
language | XML |
---|
title | Configure Shib IdP 2.2 (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 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"
backingFilexmlns="%{idp.home}/metadata/InCommon-metadata.xmlurn:mace:shibboleth:2.0:metadata"
minRefreshDelay="PT5M"metadataURL="http://md.incommon.org/InCommon/InCommon-metadata.xml"
maxRefreshDelaybackingFile="PT1H%{idp.home}/metadata/InCommon-metadata.xml"
refreshDelayFactorminRefreshDelay="0.75PT5M">
<!--
To bootstrap the trust fabric of the federation, each relying party
maxRefreshDelay="PT1H"
obtains and configures an authentic copy of the federation operator’s
refreshDelayFactor="0.75">
<!--
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 To bootstrap the trust fabric of the federation, each relying party
obtains and configures an authentic copy of the federation operator’s
$ /usr/bin/curl --silent Metadata Signing Certificate (https://dsspaces.at.incommoninternet2.orgedu/certs/inc-md-cert.pem \x/moHFAg).
Fetch the InCommon Metadata | /usr/bin/tee $IDP_HOME/credentials/inc-md-cert.pem \
Signing Certificate and check its integrity:
| /usr/bin/openssl x509 -sha1 -noout -fingerprint
$ IDP_HOME=/opt/shibboleth-idp
$ /usr/bin/curl -s https://ds.incommon.org/certs/inc-md-cert.pem \
SHA1 Fingerprint=7D:B4:BB:28:D3:D5:C8:52:E0:80:B3:62:43:2A:AF:34:B2:A6:0E:DD| /usr/bin/tee $IDP_HOME/credentials/inc-md-cert.pem \
-->
<MetadataFilter xsi:type="SignatureValidation" requireSignedMetadata="true"
certificateFile="%{idp.home}/credentials/inc-md-cert.pem" />
<!--| /usr/bin/openssl x509 -sha1 -fingerprint -noout
Require a validUntil XML attributeSHA1 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 EntitiesDescriptorroot element
of the metadata aggregate
and make sure its value is no more than 14 days into the future (i.e., the EntitiesDescriptor element) using the trusted Metadata
Signing Certificate.
-->
<MetadataFilter xsi:type="RequiredValidUntilSignatureValidation" maxValidityIntervalrequireSignedRoot="P14Dtrue" />
<!-- Consume all SP metadata in the aggregate -->
certificateFile="%{idp.home}/credentials/inc-md-cert.pem" />
<!--
<MetadataFilter xsi:type="EntityRoleWhiteList">
Require <RetainedRole>md:SPSSODescriptor</RetainedRole>
</MetadataFilter>
</MetadataProvider>
</MetadataProvider> |
To configure Shibboleth IdP 2.2 (and later) to download and verify signed InCommon metadata every hour, do the following:
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
Warning |
---|
title | Shibboleth IdP V2 is obsolete |
---|
|
The Shibboleth IdP V2 software has reached end-of-life. Upgrade to Shibboleth IdP V3 now! |
To download and verify signed InCommon metadata every hour, configure Shibboleth IdP 2.2 (and later versions of V2) as follows:
Code Block |
---|
language | xml |
---|
title | Configure Shibboleth IdP 2.2 (and later versions of V2) |
---|
collapse | true |
---|
|
<!-- 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 -s 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
The SP configuration examples in this section fetch the IdP-only InCommon production metadata aggregate. See the Metadata Aggregates wiki page for other options.
Basic Shibboleth SP Configuration
To download and verify signed InCommon metadata every hour, configure Shibboleth SP 2.5 (and later) as follows:
Code Block |
---|
language | xml |
---|
title | Configure Shibboleth SP 2.5 (and later) |
---|
collapse | true |
---|
|
<!--
The following MetadataProvider attempts to refresh the InCommon
IdP-only metadata aggregate every hour.
-->
<MetadataProvider type="XML"
url="http://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml"
backingFilePath="InCommon-metadata-idp-only.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 -s 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.
A large metadata file can cause a significant increase in startup
time at the SP. This is due to the time it takes to verify the
signature on the metadata, which is known to increase exponentially
as the size of the metadata file increases. To disable signature
verification at startup time only, add verifyBackup="false" to the
MetadataFilter element below. |
Code Block |
---|
language | XML |
---|
title | Configure Shib 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<MetadataFilter idtype="ICMDSignature" xsi:typecertificate="FileBackedHTTPMetadataProvider"inc-md-cert.pem"/>
<!--
Require a validUntil XML attribute on the xmlns="urn:mace:shibboleth:2.0:metadata"EntitiesDescriptor element
and make sure its value is no more than 14 days into the future
metadataURL="http://md.incommon.org/InCommon/InCommon-metadata.xml"-->
<MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
<!--
Consume all backingFile="/opt/shibboleth-idp/metadata/InCommon-metadata.xml"
IdP metadata in the aggregate. TIP: If the SP supports
SAML2 Web Browser SSO only, the minRefreshDelay="PT5M"md:AttributeAuthorityDescriptor
elements in IdP metadata can be ignored.
-->
<MetadataFilter maxRefreshDelaytype="PT1HEntityRoleWhiteList">
<RetainedRole>md:IDPSSODescriptor</RetainedRole>
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.4 (and later) to download and verify signed InCommon metadata every hour, do the following:
Code Block |
---|
language | XML |
---|
title | Configure Shib SP 2.4 (and later) |
---|
|
<!--
The following MetadataProvider refreshes the InCommon production metadata aggregate.
-->
<MetadataProvider type="XML"
url="http://md.incommon.org/InCommon/InCommon-metadata.xml"
backingFilePath="InCommon-metadata.xml" maxRefreshDelay="3600">
<!--
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"/>
<!-- Verify the signature on the metadata file -->
<MetadataFilter type="Signature" certificate="inc-md-cert.pem"/>
<!-- Consume all IdP metadata in the aggregate -->
<MetadataFilter type="EntityRoleWhiteList">
<RetainedRole>md:IDPSSODescriptor</RetainedRole>
<RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
</MetadataFilter>
</MetadataProvider>
|
...
<RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
</MetadataFilter>
</MetadataProvider> |
Shibboleth SP Configuration with Discovery
If your SP has a dynamic discovery interface, use this configuration instead:
Code Block |
---|
language | xml |
---|
title | Configure Shibboleth SP 2.5 (and later) with discovery |
---|
collapse | true |
---|
|
<!--
The following MetadataProvider attempts to refresh the InCommon
IdP-only metadata aggregate every hour.
The discovery interface relies primarily on mdui:DisplayName.
To fall back on md:OrganizationDisplayName if mdui:DisplayName
is missing from IdP metadata, add legacyOrgNames="true" to the
MetadataProvider element as shown below.
-->
<MetadataProvider type="XML"
url="http://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml"
backingFilePath="InCommon-metadata-idp-only.xml"
maxRefreshDelay="3600"
legacyOrgNames="true">
<!--
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 -s 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.
A large metadata file can cause a significant increase in startup
time at the SP. This is due to the time it takes to verify the
signature on the metadata, which is known to increase exponentially
as the size of the metadata file increases. To disable signature
verification at startup time only, add verifyBackup="false" to the
MetadataFilter element below.
-->
<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. TIP: If the SP supports
SAML2 Web Browser SSO only, the md:AttributeAuthorityDescriptor
elements in IdP metadata can be ignored.
-->
<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> |
See the List of IdP Display Names in InCommon Metadata to preview the IdPs that will appear on the discovery interface.
Tip |
---|
title | 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 <MetadataProvider> parent element sets the transport timeout to 120 seconds: Code Block |
---|
| <TransportOption provider="CURL" option="13">120</TransportOption> |
See the NativeSPTransportOption topic in the Shibboleth wiki for more details. |
For More Information