Extensions to MDQ

pyFF tracks https://datatracker.ietf.org/doc/draft-young-md-query/ but adds a couple of extensions that have become useful:

search

The search extensions allow pyFF to be a backend to a discovery service. The search API is pretty simple: provide a 'q' query parameter to the /entities/ endpoint results in a search. Content negotiation applies so a discovery service would typically include "Accept: application/json" in the request.

Starting with version 1.0.0 pyFF actually provides an experimental second search api at /api/search that talks directly to the underlying index and is typically much faster than the /entities/ endpoint which channels all searches through a full pipeline process. At /api/search content negotiation is strictly not necessary because only JSON is ever returned. By default the /api/search endpoint only returns IdPs.

webfinger

pyFF implements RFC7033 - aka webfinger. The pyFF server responds to a webfinger query by returning a JSON-representation of all available resources in the active database. This allows a caller to iterate over all resources (eg to mirror an MDQ structure).

Example

The following example assumes a pyFF instance running on port 8000 and that the tool jq is installed.

$ curl -s http://localhost:8000/.well-known/webfinger | jq
{
  "subject": "http://localhost:8000",
  "expires": ...,
  "links": [
    {
      "rel": "disco-json",
      "href": "http://localhost:8000/entities/"
    },
    {
      "rel": "urn:oasis:names:tc:SAML:2.0:metadata",
      "href": "http://localhost:8000/entities/"
    }
# ... many more entities ...
  ]
}

By providing the rel parameter (either set to disco-json or urn:oasis:names:tc:SAML:2.0:metadata it is possible to limit the type of links returned. In the scripts directory a tool mirror-mdq.sh uses this API to mirror an MDQ server to a remote location. This tool is useful to publish a static copy of the resources in a pyFF instance.