====== Metadata Query Service (MDQ) ======

<callout color="#ff9900" title="Pilot - Use at your own risk!">
Our Metadata Query Service is still running in pilot operation. There is currently no guarantee for its availability, flawlessness and stability. You are very welcome to share your experience or error reports with us at [[hotline@aai.dfn.de|hotline@aai.dfn.de]]. 
</callout>

===== Explanation =====
A **Metadata Query Service** can be queried for the metadata of individual entities (IdP/SP/Attribute Authority) in real-time. This approach is also called **Per-Entity Metadata**. The conventional approach is to offer federation metadata as huge xml files that have to be fetched, validated and processed by all participating systems. The per-entity approach consumes much less resources: All systems just process the metadata they need in a given moment, and cache them for a certain time. This procedure is based on the **Metadata Query Protocol** (see [[#references|References]]).

A Metadata Query Service has to meet high requirements in terms of availability and resilience. DFN-AAI's pilot lets us gain experience and improve the service for production.

Please see the section on [[en:aai:mdq#further_hints_and_known_issues|further hints and known issues]] below.

**Important notice:** The MDQ service does not deliver **any** [[de:metadata_local|local metadata]]! You still have to include them via a static metadata provider, type ''FileBackedHTTPMetadataProvider'' for Shibboleth IdPs, type ''XML'' for Shibboleth SPs.

===== Parameters =====
**URL for the production metadata (DFN-AAI, DFN-AAI-Basic) and eduGAIN:** <code>http(s)://mdq.aai.dfn.de</code>

**URL for the metadata of the test federation (DFN-AAI-Test):** <code>http(s)://mdq-test.aai.dfn.de</code>

**Certificate for the validation of the signature of DFN-AAI MDQ Metadata** (PEM format) \\
SHA256 Fingerprint: 75:18:98:F6:E8:23:21:E8:B1:DC:71:6B:D0:AB:50:F0:C2:DB:9D:CE:4B:2B:A1:88:B1:42:DB:99:13:DB:0D:E9 \\
https://www.aai.dfn.de/metadata/dfn-aai-mdq.pem 

===== Examples =====

==== Shibboleth IdP 4.x ====

=== Production (DFN-AAI, DFN-AAI-Basic) and eduGAIN ===

<file xml ./conf/metadata-providers.xml>
    <MetadataProvider id="dfn_aai_mdq_prod" xsi:type="DynamicHTTPMetadataProvider"
                  maxCacheDuration="PT1H" minCacheDuration="PT10M">
           <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
                  certificateFile="/etc/ssl/aai/dfn-aai-mdq.pem"/>
           <MetadataQueryProtocol>http://mdq.aai.dfn.de</MetadataQueryProtocol>
    </MetadataProvider>
</file>

=== Test Federation (DFN-AAI-Test) ===

<file xml ./conf/metadata-providers.xml>
    <MetadataProvider id="dfn_aai_mdq_test" xsi:type="DynamicHTTPMetadataProvider"
                  maxCacheDuration="PT1H" minCacheDuration="PT10M">
           <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
                  certificateFile="/etc/ssl/aai/dfn-aai-mdq.pem"/>
           <MetadataQueryProtocol>http://mdq-test.aai.dfn.de</MetadataQueryProtocol>
    </MetadataProvider>
</file>


==== Shibboleth SP 3.2.x ====

<callout color="#ff9900" title="Important Notice">
Importing metadata via MDQ only makes sense if **the SP does not rely on imported federation metadata to generate an IdP list for its Discovery Service**. This is how [[de:shibsp#shibboleth_eds_embedded_discovery_service|Shibboleth EDS]] (Link in German) works.  
</callout>

=== Production (DFN-AAI, DFN-AAI-Basic) and eduGAIN ===

<file xml /etc/shibboleth/shibboleth2.xml>
    <MetadataProvider type="MDQ" id="dfn_aai_mdq_prod" ignoreTransport="true"
                  cacheDirectory="mdq-aai-dfn-de"
                  maxCacheDuration="3600" minCacheDuration="600"
                  baseUrl="https://mdq.aai.dfn.de">
           <MetadataFilter type="Signature" certificate="/etc/ssl/aai/dfn-aai-mdq.pem"/>
    </MetadataProvider>
</file>

We are happy to document further filter mechanisms [[hotline@aai.dfn.de|on demand]].

===== Further hints and known issues =====
**General:** \\
If you have defined static metadata providers (e.g. ''FileBackedHTTPMetadataProvider'') in addition to dynamic metadata query, the ''MDQ'' resp. ''DynamicHTTPMetadataProvider'' should be appended after the static ones. This prevents the IdP/SP from running metadata queries for entities that are available from the static metadata.

**Shibboleth IdP:** \\
Failed metadata queries are logged like this in the IdP: ''Document root was not an EntityDescriptor: org.opensaml.saml.saml2.metadata.impl.EntitiesDescriptorImpl''

**Shibboleth SP < 3.2.0:** \\
After every restart the SP logs a misleading warning about the cache directory that cannot be created. It already exists. See https://issues.shibboleth.net/jira/browse/SSPCPP-916

Please let us know if you run into any **other errors** ([[hotline@aai.dfn.de|hotline@aai.dfn.de]]).

\\

===== References =====
  * [[https://datatracker.ietf.org/doc/draft-young-md-query/|Specification of the Metadata Query Protocol]]
  * Shibboleth Wiki
    * [[https://wiki.shibboleth.net/confluence/display/IDP4/MetadataManagementBestPractices#MetadataManagementBestPractices-DynamicHTTPMetadataProvider|Metadata Management Best Practices]]
    * [[https://wiki.shibboleth.net/confluence/display/IDP4/DynamicHTTPMetadataProvider|Identity Provider Configuration]]
    * [[https://wiki.shibboleth.net/confluence/display/SP3/MDQMetadataProvider|Service Provider Configuration]]
  * Detailed [[https://spaces.at.internet2.edu/display/MDQ/Introducing+per-entity+metadata+service|documentation on InCommon Wiki]] (US federation)

{{tag>metadata idp4 sp3 mdq}}