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):
- The Metadata Query Server's base URL
- A single "/" character, unless the base URL already ends in a "/"
- The string "entities/"
- A single URL-encoded
For example, if the base URL is
entityID is , the request URL is
A Command-Line Tool for Testing a Metadata Query Server
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
entityID and uses that to construct a request URL to an instance of a Metadata Query Server. The bash function above is included in the shell script.