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

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   Single-Entity Metadata Retrieval
  • 2.3   Metadata Collection Retrieval
  • 2.4   Common Query Parameters
  • 2.5   HTTP Transport
• 3.   Considerations
  • 3.1   ID Assignment
  • 3.2   Efficient Retrieval and Caching
  • 3.3   Security Considerations
• 4.   References
• Author's Address
• Intellectual Property and Copyright Statements

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

2.2 Single-Entity Metadata Retrieval

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

2.2.1 Request

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.

2.2.2 Response

The response to a Unique Metadata Retrieval request MUST be a document that provides metadata for one, singular, entity.

2.2.3 Example Request/Response

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

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

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

2.3.2 Response

The response to a Metadata Collection Retrieval request MUST be a document that describes a collection of entities.

2.3.3 Example Request/Response

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

2.4 Common Query Parameters

The following query parameter MAY be use with either retrieval messages:

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

2.5 HTTP Transport

2.5.1 HTTP Version

A responder MUST support HTTP version 1.1 [HTTP11] .

2.5.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.5.3 Response Headers

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

Content-MD5 - This header SHOULD be present.

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

ETag - This header MUST be present.

2.5.4 Content Encoding

All responders MUST support the gzip content compression.

2.5.5 Authentication

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

3. Considerations

3.1 ID Assignment

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.

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

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

4. References

Author's Address