Metadata Aggregate Protocol - Retrieval
metadata-aggregate-protocol-retrieval-02

Abstract

This document defines a set of protocol request/response pairs used to retrieve entity metadata from a metadata aggregation service.

Table of Contents

• 1.   Introduction
  • 1.1   Notation and Convention
  • 1.2   Terminology
• 2.   Protocols for the Retrieval of Entity Metadata
  • 2.1   Base URL
  • 2.2   Identifiers
  • 2.3   Single-Entity Metadata Retrieval
  • 2.4   Metadata Collection Retrieval
  • 2.5   Common Query Parameters
  • 2.6   HTTP Transport
• 3.   Considerations
  • 3.1   Efficient Retrieval and Caching
  • 3.2   Security Considerations
• 4.   References
• Author's Address

• Figure 1: Example Unique Metadata Retrieval Request
• Figure 2: Example Unique Metadata Retrieval Response
• Figure 3: Example Unique Metadata Retrieval Request
• Figure 4: Example Unique Metadata Retrieval Response

1. Introduction

1.1 Notation and Convention

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] .

1.2 Terminology

entity - A single logical construct for which metadata may be asserted. Generally this is a network accessible service.

metadata - A machine readable description of certain entity characteristics. Generally metadata provides information such as end point references, service contact information, etc.

metadata aggregator - A service which responds to metadata aggregate retrieval requests.

2. Protocols for the Retrieval of Entity Metadata

This set of messages is defined to support the retrieval of entity metadata from a responder.

2.1 Base URL

Each retrieval request is performed by issuing an HTTP GET request to 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 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 included the path required by the particular retrieval request is appended to path in the base URL.

2.2 Identifiers

The following protocol messages use identifiers to reference metadata for single entities as well as collections of entities. The assignment of such identifiers to a particular metadata document (whether it represents a single entity or a collection of them) is the responsibility of the metadata aggregator. An identifier MUST correspond to, at most, one unique document. However, a single unique document MAY have more than one identifier. If a metadata document already contains a well known identifier it is RECOMMENDED that the metadata aggregator uses such natural identifiers unless doing so would cause a collision with an existing entry.

Some protocols employ a transformed version of the ID. This may be done to reduce the overall size of the identifier, escape special characters, obfuscate the identifier, or for various other reasons. A metadata aggregator servicing such protocol MAY identify these IDs by prepending the string '{' + transformation indicator + '}' to the transformed identifier, thus forming a new, unique, identifier. For example, the identifier

http://example.org/service

transformed by means of MD5 hashing would become

{md5}f3678248a29ab8e8e5b1b00bee4060e0

The transformation indicator MUST be composed exclusively of printable ASCII character (0x21-0x7E) excluding '{' (0x7B) and '}'(0x7D). Such an identifier need only make sense in the context of the protocol which it is used. As hashing is a common transformation it is RECOMMENDED that the identifiers 'md5', 'sha1', 'sha256', and 'sha512' be used when those hashing functions are employed as the transformation method.

2.3 Single-Entity Metadata Retrieval

This protocol message is used to retrieve a metadata document describing a single entity.

2.3.1 Request

A Unique Metadata Retrieval Request is performed by issuing an HTTP GET request. All Single-Entity 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.

2.3.2 Response

The response to a Unique Metadata Retrieval request MUST be a document that provides metadata for one, singular, entity. In the event that no metadata is registered for the given ID an HTTP 404 (resource not found) status code is returned.

2.3.3 Example Request/Response

    GET /service/entity/http%3A%2F%2Fexample.org%2Fidp 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

2.4 Metadata Collection Retrieval

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, for example, represent all entities participating in a particular community.

2.4.1 Request

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. The collection name '@all' MUST correspond to the complete collection of metadata that the requester is entitled to view. All other IDs beginning with the at symbol ('@') are reserved.

2.4.2 Response

The response to a Metadata Collection Retrieval request MUST be a document that describes a collection of entities. In the event that no collection is registered for the given ID an HTTP 404 (resource not found) status code is returned. In the event that the collection exists, but is empty, an HTTP status code of 200 should be returned with an empty body.

2.4.3 Example Request/Response

    GET /service/entity-collection/euentities 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

2.5 Common Query Parameters

The following query parameter MAY be used with either retrieval message:

requester - This optional parameter provides carries the self-asserted identity of the requester.

2.6 HTTP Transport

2.6.1 HTTP Version

A responder MUST support HTTP version 1.1 [HTTP11] .

2.6.2 Request Headers

The following HTTP Headers are of special interest to retrieval requests:

Accept - This header MUST be present and MUST indicate the type of metadata to be returned. For example, the content-type application/samlmetadata+xml would be used to indicate a request for SAML metadata [SAMLMD] .

Accept-Encoding - The requester SHOULD support gzip content encoding and SHOULD advertise its support of this encoding by means of this header.

2.6.3 Response Headers

The following HTTP headers are of special interest to retrieval responses:

Content-Type - This header MUST be present and MUST indicate the type of metadata returned.

ETag - This header MUST be present.

2.6.4 Content Encoding

All responders MUST support the gzip content encoding.

2.6.5 Authentication

The responder MUST support HTTP basic authentication and SHOULD support X.509 mutual TLS authentication.

3. Considerations

3.1 Efficient Retrieval and Caching

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 conditional queries, based on the ETag when they query for updates.

3.2 Security Considerations

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 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.

4. References

Author's Address