Aggregated Service Discovery
draft-daboo-aggregated-service-discovery-02

Abstract

This specification describes how clients can discover multiple services to configure themselves with a minimum of user-provided information, as short as possible sequence of queries and with a minimum of overhead for administrators of the services.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on July 13, 2013.

Copyright Notice

Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 2. Open Issues
• 3. Conventions Used in This Document
• 4. Overview
• 5. Aggregated Service Discovery Document Format
• 5.1. Extensions to the Document Format
• 5.2. Service names
• 6. Finding the Aggregated Service Discovery Information
• 7. Handling multiple, alternative services
• 8. Internationalization Considerations
• 9. Security Considerations
• 10. IANA Considerations
• 10.1. Well-Known URI Registration
• 10.1.1. servicediscovery Well-Known URI Registration
• 11. Acknowledgments
• 12. References
• 12.1. Normative References
• 12.2. Informative References
• Appendix A. Change History (to be removed prior to publication as an RFC)
• Appendix B. Example of multiple services
• Appendix C. Example - multiple, alternative mail retrieval services
• Authors' Addresses

1. Introduction

There are currently various systems in place for discovery and configuration of individual protocols, but the process can often require an extensive series of requests using different protocols to discover all of the details needed to set up the various client services which an individual might use to interact with an organisation or service provider.

Consider Jason, a new employee at Example Enterprises. Jason needs to configure his e-mail program to use IMAP [RFC3501] + TLS on port 143 against mail.example.com, he needs to send mail on port 8557 via TLS+SMTP to smtp.example.com, his calendar is on port 8443 at https://caldav.example.com:8443/calendar/, and so forth. Some of these things can be discovered relatively easily, with a combination of DNS queries (including SRV lookups, certificate checking, and http requests). However, each protocol has its own requirements and settings and each has to be done separately. Whilst the client can "hide" the multiple service setup from the user, the actual implementation often requires separate code and processes to manage, making it more complex that it needs to be.

This specification defines a single protocol which will allows for discovery of a variety of services in a single call, allowing developers to simplify the coding and user interface in client software, and in particular in multi-function client software such as a combined e-mail and calendar client. Discovery is accomplished via a retrieval of a single document from a server, improving performance over per-service discovery mechanisms that require multiple network operations. In addition, complex dependencies between different services can be easily represented, so that, for example, some services can be prioritized over others, or grouped together by "logical" function. Further, rich information about each service can be included, such as details about required transport layer security or authentication.

2. Open Issues

1. Is it OK to embed certificate details for the actual services or a root certificate?

3. Conventions Used in This Document

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

4. Overview

The following outlines the steps a client carries out to setup multiple services for a user:

1. The client software is expected to capture a user identifier and domain name (possibly entered in the form of an email address) from the user, and possibly authentication information. e.g., 'cyrus@example.com'.
2. The client would make an initial DNS SRV [RFC2782] query for '_servicediscovery._tcp.example.com'. The result of the SRV lookup will be a hostname that is then used in place of the user supplied domain name for the next steps. If the SRV lookup is unsuccessful, then the user supplied domain name is used for the next steps.
3. The client then makes an HTTP GET request [RFC2616] against the server, using TLS [RFC2818], requesting the URL 'https://{domain name}/.well-known/servicediscovery?id={user identifier}', where '{domain name}' is the host name determined from step #2, and '{user identifier}' is the user supplied identifier from step #1. The client will follow any redirects and respond to any authentication challenges. Where the user did not provide an appropriate authentication token in the first step the client software will prompt for it at this point
4. The client will receive a JSON [RFC4627] document in step #3 conforming to the format described in Section 5. The client parses this document to extract information about the available services. At that point it can either present a list of services to the user so that they can decide exactly what they want setup, or it can automatically setup services for all those it supports.

5. Aggregated Service Discovery Document Format

The aggregated service discovery document is an JSON [RFC4627] document. The document contains a single object with two members representing two pieces of information: overall service provider information (e.g., name, icon "badge", contact information), and a list of each service supported. Each service will contain some information common to each type of service, and then information specific to each service.

The JSON document format is defined here using the syntax in [I-D.newton-json-content-rules]. An example of such an aggregated service discovery document for some common services is shown in Appendix B.

JSON Content Rules for the JSON document returned for a "capabilities" action request.

; root object

root {
  provider,
  entries
}

; ----- provider -----

; Contains information describing the service provider, that can be
; used by clients to "group" individual services together under a
; common name or section when presenting details to the user.
provider "provider" {
  provider_name,
  ?description,
  ?image,
  ?contact,
  ?manage,
  ?password_reset,
  ?ttl
}

; The name for the service provider.
provider_name "name" : string

; The description of the service provider.
description "description" : string

; A URI for an image that can be used as an "icon" for the service
; provider. The URI SHOULD be an http or https URI and clients
; SHOULD use standard HTTP Accept header behavior to request an
; appropriate image format from the server (see Section 14.1 of
; [RFC2616]). The image SHOULD NOT exceed a size of 128 x 128
; pixels.
image "image" : uri

; Contact information for the service provider.
contact "contact" {
  email / (?email, uri)
}

; An email address that can be used to contact the service
; provider.
email "email" : email

; A URI for a webpage providing information about the service
; provider.
url "url" : uri

; A URI for a webpage where a user can manage details of their
; account.
; e.g., a place where users can go to add additional (possibly
; payment required) services.
manage "manage" : uri

; A URI for a webpage where a user can change their account
; password.
password_reset "password-reset" : uri

; The minimum interval in seconds which clients SHOULD wait
; before re-fetching the document to check for changes.
ttl "ttl" : integer

; ----- entries -----

; List of services.
entries "entries" [ *entry ]

entry {
  name,
  service,
  ?(group, priority),
  uri / (host, ?port),
  ?tls,
  ?auth,
}

; A description for the service.
name "name" : string

; The service type. See below for details of the value used.
service "service" : string

; Identifies the nature of the service to allow similar services to
; be grouped together.
group "group" : string

; Identifies the nature of the service to allow similar services to
; be grouped together.
priority "priority" : integer 1

; The URI used to contact the server providing the service.
uri "uri" : uri

; The hostname of the server providing the service.
host "host" : string

; The network port number of the server providing the service.
port "port" : integer 0..65535

; Provides detail of transport layer security to be used with the
; service.
tls "tls" {
  ?required,
  ?at_start,
  ?certificates
}

; Indicates that clients MUST use transport layer security when
; connecting to the server providing the service.
required "required" : boolean

; Indicates that clients MUST initiate TLS immediately upon
; connecting to the server rather than using an "in-protocol"
; upgrade mechanism.
at_start "at-start" : boolean

; List of certificates.
certificates "certificates" [ *certificate ]

; Details about the TLS certificate the server will use. Clients
; MAY use the specified certificate information to validate any TLS
; connection to the server, otherwise existing rules for the target
; protocol are used.
certificate "certificate" {
  cert_name /
  fingerprint /
  public_key
}

; The name of the certificate.
cert_name "name" : string

; The fingerprint of the certificate.
fingerprint "fingerprint" : string

; The fingerprint of the certificate.
public_key "public-key" : string

; List of authentication methods to use in server preferred order.
; If the protocol supports SASL [RFC4422] then this is a list of
; SASL authentication mechanisms, otherwise it is a protocol
; specific list of names. In either case, clients MUST NOT use
; a mechanism that is not advertised in this list.
auth "auth" [ *string ]

5.1. Extensions to the Document Format

Additional members can be added to the JSON document root, "provider" or "entries" objects with the following rules:

1. Standards based members MUST be defined in an RFC and registered with IANA. TBD - precise details of this and IANA registry setup.
2. Member names that include a prefix of the form "{...}", where the contents of the curly braces is a vendor id, are considered to be vendor specific private extensions which do not require registration. TBD nature of vendor id.

Clients SHOULD ignore all extension member elements that they are unable to process.

5.2. Service names

The "service" member in the "entry" object is used to convey an identifier for the type of service being described. This can have one of two forms:

1. An identifier from the IANA ports registry defining a service type.
2. Identifiers that include a prefix of the form "{...}", where the contents of the curly braces is a vendor id, are considered to be vendor specific private service type. TBD nature of vendor id.

6. Finding the Aggregated Service Discovery Information

A ".well-known" URI is registered by this specification: "servicediscovery" (see Section 10). This URI points to a resource that the client can use to retrieve the aggregated service discovery document for the site. Clients MUST handle HTTP redirects on the ".well-known" URI, but MUST NOT allow a redirect to an insecure URI. Clients MUST handle HTTP authentication on the ".well-known" URI. Servers MUST require clients to authenticate if there is any sensitive or per-user information in the document.

When requesting the document clients MUST include a URI query parameter "id" set to the user identifier entered by the user. When responding to the request, the server MUST tailor the aggregated service discovery document for the user making the request and MUST require HTTP authentication by that user before returning the document.

Clients SHOULD cache the document for a period of time no less than the value of the "ttl" member in the "provider" object, or for a minimum of 24 hours of no "ttl" member is present.

7. Handling multiple, alternative services

The "group" and "priority" members of an entry provide a way for a service provider to distinguish multiple services of the same type, as well as allow the client to select the most appropriate service when several alternatives exist.

For example, consider the case of a service provider supporting two separate email retrieval services, one the "primary" account, and the other for "internal" messaging only. It is expected that clients configure accounts for both services. Each service also offers either IMAP [RFC3501] or POP3 [RFC1939] as an email retrieval protocol. In this case the aggregated service discovery document would contain four entry items: two describing an IMAP service and two describing a POP3 service. Each entry would contain a "group" member that groups one IMAP and one POP3 service together for each of the "primary" and "internal" account groups. Each entry would also contain a "priority" member indicating the service providers preference for clients to use either IMAP or POP3. An example of such an aggregated service discovery document is shown in Appendix C.

When a client retrieves and processes such a document, it would first group services based on the SD:application value. For each group, it iterates over the list of entries in the group, ordered by SD:priority values, and configures an account for the first one it finds with an SD:service that it supports.

8. Internationalization Considerations

Some elements of the service discovery document can contain human readable text that clients might choose to present to a user. Clients SHOULD use the Accept-Language header behavior described in Section 14.4 of [RFC2616] to ensure the server can return a document suitable for the user's chosen language. Servers SHOULD support variations of the service discovery document based on language, returning the appropriate variation in response to client requests.

9. Security Considerations

When using an SRV lookup to discover a server hosting the service discovery document, a malicious attacker with access to the DNS server data, or able to get spoofed answers cached in a recursive resolver, can potentially cause clients to connect to a server hosting a bogus service discovery document with service data chosen by the attacker. In the absence of a secure DNS option, clients SHOULD check that the target FQDN returned in the SRV record matches the original service domain that was queried. If the target FQDN is not in the queried domain, clients SHOULD verify with the user that the SRV target FQDN is suitable for use before executing any connections to the host.

HTTP requests for the service-discovery document MUST be performed via TLS. Clients MUST use the procedure outlined in Section 4.3 of [RFC6125] to verify the service.

10. IANA Considerations

10.1. Well-Known URI Registration

This document defines a ".well-known" URI using the registration procedure and template from Section 5.1 of [RFC5785].

10.1.1. servicediscovery Well-Known URI Registration

URI suffix:

servicediscovery

Change controller:

IETF.

Specification document(s):

This RFC.

Related information:

None.

11. Acknowledgments

The authors would like to thank the following individuals for contributing their ideas and support for writing this specification: Andrew Biggs, Mike Douglass, Joe Hildebrand, and Stepan Potys

The authors would also like to thank CalConnect, The Calendaring and Scheduling Consortium, for advice with this specification.

12. References

12.1. Normative References

12.2. Informative References

Appendix A. Change History (to be removed prior to publication as an RFC)

Changes in -02:

1. Switched to JSON document format.

Changes in -01:

1. Renamed various elements for clarity.
2. Added an SD:manage element.
3. Added a section on handling of multiple, alternative services, together with a second appendix example.

Appendix B. Example of multiple services

GET /.well-known/servicediscovery?id=cyrus@example.com HTTP/1.1
Host:example.com:443
Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl
Content-Type: application/json
Content-Length: xxx

{
  "provider" : {
    "name" : "Super-duper ISP",
    "description" : "Super-duper ISP is the home for all your data.",
    "contact" : {
      "email" : "superduper@example.com",
      "uri" : "http://www.example.com"
    },
    "manage" : "http://www.example.com/myaccount.html",
    "ttl" : 2592000
  },
  
  "entries" : [
    {
      "name" : "Corporate Mail",
      "service" : "imap",
      "group" : "mail-access-1",
      "priority" : 2,
      "uri" : "imap:imap.example.com",
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Corporate Mail",
      "service" : "pop3",
      "group" : "mail-access-1",
      "priority" : 1,
      "host" : "mail.example.com",
      "port" : 110,
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Corporate Mail",
      "service" : "submission",
      "host" : "mail.example.com",
      "port" : 587,
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Corporate Calendar",
      "service" : "caldav",
      "uri" : "https://calendar.example.com",
      "tls" : {
        "required" : true,
        "at-start" : true
      },
      "auth" : ["Digest"]
    },

    {
      "name" : "Corporate Contacts",
      "service" : "carddav",
      "uri" : "https://contacts.example.com",
      "tls" : {
        "required" : true,
        "at-start" : true
      },
      "auth" : ["Digest"]
    }
  ]
}

Appendix C. Example - multiple, alternative mail retrieval services

GET /.well-known/servicediscovery?id=cyrus@example.com HTTP/1.1
Host:example.com:443
Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl
Content-Type: application/json
Content-Length: xxx

{
  "provider" : {
    "name" : "Mail Agrregator ISP",
    "description" : "Primary and internal email services.",
    "contact" : {
      "email" : "emails@example.com",
      "uri" : "http://www.example.com"
    },
    "manage" : "http://www.example.com/myaccount.html",
    "ttl" : 2592000
  },
  
  "entries" : [
    {
      "name" : "Primary Mail",
      "service" : "imap",
      "group" : "primary",
      "priority" : 2,
      "uri" : "imap:mail.example.com",
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Primary Mail",
      "service" : "pop3",
      "group" : "primary",
      "priority" : 1,
      "host" : "mail.example.com",
      "port" : 110,
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Internal Mail",
      "service" : "imap",
      "group" : "internal",
      "priority" : 2,
      "uri" : "imap:int.example.com",
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    },

    {
      "name" : "Internal Mail",
      "service" : "pop3",
      "group" : "internal",
      "priority" : 1,
      "host" : "int.example.com",
      "port" : 110,
      "tls" : {
        "required" : true
      },
      "auth" : ["CRAM-MD5"]
    }

    {
      "name" : "Internal Mail",
      "service" : "{example.com}webmail",
      "group" : "internal",
      "priority" : 1,
      "uri" : "https://int.example.com/webmail",
      "{example.com}bookmark": "https://int.example.com/webmail"
    }
  ]
}

This example shows two different email services: "Primary Mail" (which has both IMAP4 and POP3 services available), and "Internal Mail" (which additionally has a private "webmail" service available). An extension member is also specified for the "webmail" service.

Authors' Addresses