Automated Service Configuration

Automated Service Configuration Morphoss Ltd

6 Karoro Place Porirua 5024 New Zealand andrew@morphoss.com http://www.morphoss.com/

Apple Inc.

1 Infinite Loop Cupertino CA 95014 USA cyrus@daboo.name http://www.apple.com/

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

There are currently various systems in place for discovery and configuration of individual services, 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 + 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 allow for retrieval of a variety of service configuration information 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 clients. Configuration is retrieved from a single document on a server, improving performance over per-service configuration 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. This protocol is intended to provide a simple one-way retrieval of configuration information, with the data flow from service provider to client, building on successful technologies such as HTTP and JSON to accomplish its goals. As such it differs from other "client configuration" orientated protocols, such as ACAP, which have not had much deployment success due to complexity introduced by having a a two-way exchange of data, and the resulting need to keep multiple clients synchronized as changes occur.

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

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 .

The following outlines the steps a client carries out to setup multiple services for a user: 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'. The client uses the WebFinger protocol to request a link relation with the value "service-configuration", using the identifier supplied by the user, following any redirects and responding to any authentication challenges. The client retrieves a JSON document conforming to the format described in from the target of the link relation returned in Step #2. 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.

The automated service configuration document is an JSON 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 . An example of such an automated service configuration document for some common services is shown in .

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

Additional members can be added to the JSON document root, "provider" or "entries" objects with the following rules: Standards based members MUST be defined in an RFC and registered with IANA. TBD - precise details of this and IANA registry setup. 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.

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: An identifier from the IANA ports registry defining a service type. 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.

This specification makes use of the WebFinger protocol to allow a client to find a link to the automated service configuration document corresponding to an identifier supplied by a user. This specification registers the "service-configuration" link relation type for use with WebFinger, to identify the links for automated service configuration documents. When the client makes a WebFinger request, it SHOULD use the "rel" query parameter, defined in Section 4.3 of , to ensure the relevant link relations are returned. The URI referenced by the links MUST be an HTTPS URI, and MUST point to a resource that the client can use to retrieve the automated service configuration document for the site. Servers can return multiple "service-configuration" links in the webfinger response. Clients SHOULD treat each link as separate, complementary services available to the user. When requesting automated service configuration documents, clients MUST include a URI query parameter "id" set to the user identifier entered by the user. Clients MUST handle HTTP redirects on the link URI, but MUST NOT allow a redirect to an insecure URI. When responding to the request, the server MUST tailor the automated service configuration 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.

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 or POP3 as an email retrieval protocol. In this case the automated service configuration 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 automated service configuration document is shown in . 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.

Some elements of the automated service configuration 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 to ensure the server can return a document suitable for the user's chosen language. Servers SHOULD support variations of the automated service configuration document based on language, returning the appropriate variation in response to client requests.

When using WebFinger to discover a server hosting the automated service configuration 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 automated service configuration 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 link relation URI 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 link URI target FQDN is suitable for use before executing any connections to the host. HTTP requests for the automated service configuration document MUST be performed via TLS. Clients MUST use the procedure outlined in Section 4.3 of to verify the service.

This document defines a "service-configuration" link relation type using the registration procedure and template from Section 6.2 of .

service-configuration Refers to an automated service configuration document This RFC.

The authors would like to thank the following individuals for contributing their ideas and providing feedback for writing this specification: Andrew Biggs, Mike Douglass, Joe Hildebrand, Paul Jones, Markus Lanthaler, Matt Miller, Stepan Potys, and Peter Saint-Andre The authors would also like to thank CalConnect, The Calendaring and Scheduling Consortium, for advice with this specification.

&I-D.newton-json-content-rules; &I-D.ietf-appsawg-webfinger; &rfc2119; &rfc2616; &rfc2818; &rfc4422; &rfc4627; &rfc5988; &rfc6125; &rfc1939; &rfc2244; &rfc3501;

Changes in -03: Fix examples to properly show request/response headers. Title change. Added text to the Introduction to differentiate this from other protocols. Switched to WebFinger instead of SRV. Changes in -02: Switched to JSON document format. Changes in -01: Renamed various elements for clarity. Added an SD:manage element. Added a section on handling of multiple, alternative services, together with a second appendix example.

First comes the WebFinger request to retrieve the appropriate link relation.

> Request << GET /service-config?id=cyrus@example.com HTTP/1.1 Host:example.com:443 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl >> Response << HTTP/1.1 200 OK Date: Wed, 20 Feb 2013 09:32:12 GMT 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"] } ] } ]]>

First comes the WebFinger request to retrieve the appropriate link relation.

> Request << GET /.well-known/webfinger? resource=acct:cyrus@example.com& rel=service-configuration HTTP/1.1 Host:example.com:443 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl >> Response << HTTP/1.1 200 OK Date: Wed, 20 Feb 2013 09:32:12 GMT Content-Type: application/jrd+json Content-Length: xxx { "subject" : "acct:cyrus@example.com", "links" : [ { "rel" : "service-configuration", "type" : "application/json", "href" : "https://example.com/service-config" } ] } ]]> Next is the retrieval of the automated service configuration document using the URI from the WebFinger link relation. 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.

> Request << GET /service-config?id=cyrus@example.com HTTP/1.1 Host:example.com:443 Authorization: basic QmFzZTY0IGlzIGVhc3kgdG8gZGVjb2Rl >> Response << HTTP/1.1 200 OK Date: Wed, 20 Feb 2013 09:32:12 GMT 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" } ] } ]]>

TODO: example of webfinger returning multiple "service-configuration" links.