metadata-aggregate-protocol-retrieval-01 | C.L. La Joie |
June 8, 2009 | SWITCH |
Metadata Aggregate Protocol - Retrieval
metadata-aggregate-protocol-retrieval-01
This document defines a set of protocol request/response pairs used to retrieve entity metadata from a metadata aggregation service.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 [RFC2119] .
This set of messages is defined to support the retrieval of entity metadata from a responder.
Each retrieval request is performed by issuing an HTTP GET request a particular URL. Such URLs are required to have a particular path. A base URL proceeds this path. Such a base URL MUST contain at the least the scheme and host name components. It MAY also include a port as well as a path. It MUST NOT include any fragments. If a path is include the path required by the particular retrieval request is appended.
This protocol message is used to retrieve a metadata document describing a single entity.
A Unique Metadata Retrieval Request is performed by issuing an HTTP GET request. All Unique Metadata Retrieval requests MUST use the URL format:
<base_url>/entity/{id}
where the ID uniquely identifies an entity metadata document. The ID MUST be properly URL encoded. All IDs beginning with the at symbol ('@') are reserved.
The response to a Unique Metadata Retrieval request MUST be a document that provides metadata for one, singular, entity.
GET /service/entity/http%3A%2F%2Fexample.org%2Fidp?requester=http%3A%2F%2Fexample.org%2Fsp HTTP/1.1 Host: metadata.example.org Accept: application/samlmetadata+xml Accept-encoding: deflate, gzip
Figure 1: Example Unique Metadata Retrieval Request
HTTP/1.x 200 OK Content-Type: application/samlmetadata+xml ETag: abcdefg Content-Length: 1234 <EntityDescriptor entityID="http://example.org/idp"> .....
Figure 2: Example Unique Metadata Retrieval Response
This protocol message is used to retrieve a metadata document describing a collection of entities. The meaning of such a collection is out of scope for this document. Such collections may represent a, for example, all entities participating in a particular community.
A Metadata Collection Retrieval Request is performed by issuing an HTTP GET request All Metadata Collection Retrieval requests MUST use the URL format:
<base_url>/entity-collection/{id}
where the ID uniquely identifies a the metadata of a collection of entities. The ID MUST be properly URL encoded. All IDs beginning with the at symbol ('@') are reserved. The id '@all' MUST correspond to the complete collection of metadata that the request is entitled to view.
The response to a Metadata Collection Retrieval request MUST be a document that describes a collection of entities.
GET /service/entity-collection/euentities?requester=http%3A%2F%2Fexample.org%2Fsp HTTP/1.1 Host: metadata.example.org Accept: application/samlmetadata+xml Accept-encoding: deflate, gzip
Figure 3: Example Unique Metadata Retrieval Request
HTTP/1.x 200 OK Content-Type: application/samlmetadata+xml ETag: abcdefg Content-Length: 1234 <EntitiesDescriptor> .....
Figure 4: Example Unique Metadata Retrieval Response
The following query parameter MAY be use with either retrieval messages:
A responder MUST support HTTP version 1.1 [HTTP11] .
The following HTTP Headers are of special interest to retrieval requests:
The following HTTP headers are of special interest to retrieval responses:
All responders MUST support the gzip content compression.
The responder MUST support HTTP basic authentication and SHOULD support X.509 mutual TLS authentication.
The assignment of IDs to a particular metadata document (whether it represents a single entity or a collection of them) is the responsibility of the responder. However, it is RECOMMENDED that the responder use an ID already associated with the entity. Most metadata documents, or associated application protocols, already assign a unique ID to entities, such an ID would be a good candidate. Obviously care must be taken to ensure that IDs do not conflict. Also note that the more than one ID MAY refer to the same metadata document.
Techniques for the efficient retrieval and caching of information helps improve performance and decrease load on various resources. It is RECOMMENDED that requesters support gzip compress content type encoding in order to reduce load on the network. In addition it is RECOMMENDED that requesters cache retrieval results and use the conditional queries, based on the ETag when they query for updates.
While a requester may provide a claimed identity by means of the 'requester' query parameter a responder SHOULD NOT trust this unless it can be verified through some authentication mechanism. Once the identity of the requester is established the responder MAY apply certain access control policies to determine whether a particular request is allowed to access the requested metadata.
As metadata often contains information necessary for the secure operation of interacting services it is RECOMMENDED that some form of content integrity checking be performed. This may include the use of SSL/TLS at the transport layer, digital signatures present within the metadata document, or any other such mechanism. While it is recommended that responders provider an MD5 hash of the content returned, this information should not serve as the sole source of integrity checking as an attacker may be able to manipulate this data.
[HTTP11] | UC Irvine, Compaq/W3C, Compaq, W3C/MIT, Xerox, Microsoft, and W3C/MIT, “Hypertext Transfer Protocol -- HTTP/1.1”, June 1999, <http://www.w3.org/Protocols/rfc2616/rfc2616.html>. |
[RFC2119] | Harvard University, “Key words for use in RFCs to Indicate Requirement Levels”, March 1997, <http://tools.ietf.org/html/rfc2119>. |
[SAMLMD] | Internet2, Sigaba, RSA Security, and Sun Microsystems, “Metadata for the OASIS Security Assertion Markup Language”, March 2005, <http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf>. |