The Metadata Query Protocol is a REST-like API for requesting and receiving arbitrary metadata. The specification is currently broken into two parts: a base specification (draft-young-md-query) that makes no assumption about metadata format and a SAML profile of the base specification (draft-young-md-query-saml) that focuses on SAML metadata. This document (the one you are reading right now) gives a brief overview of the two specifications taken together.
Historically, section 4 of the OASIS SAML2 Metadata specification outlines two methods of SAML metadata publication and resolution, both of which rely on the SAML
entityID, a globally unique URI. The first method resolves a metadata resource by mapping the
entityID directly to the resource (by value) whereas the second method maps the
entityID indirectly (by reference) via DNS. Both methods have inherent limitations, and hence the Metadata Query Protocol was created. The latter still uses the
entityID as input to the resolution process but now a Metadata Query Server is responsible for mapping the
entityID to the desired metadata resource.
By definition, a Metadata Query Server implements the Metadata Query Protocol. A reference implementation for the latter is Ian Young's Metadata Query Server (mdq-server) based on the Shibboleth Metadata Aggregator software. The InCommon Federation's metadata service is a real-world deployment instance of mdq-server.
As defined in the base specification, a metadata query request URL is constructed by concatenating the following four components (two of which are variable):
For example, if the base URL is
entityID is , the request URL is
A bash function to construct a request URL per the Metadata Query Protocol specification, and a command-line tool (called md_query.sh) based on that function, are stored on GitHub.
You can experiment with the Metadata Query Protocol by using a shell script (called md_query.sh) to fetch SAML metadata at the command line. The script automatically URL-encodes an arbitrary