idnits 2.17.1 draft-jones-webfinger-email-autoconfig-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (July 8, 2019) is 1747 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 265 -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Jones 3 Internet-Draft G. Salgueiro 4 Intended status: Standards Track Cisco 5 Expires: January 9, 2020 July 8, 2019 7 WebFinger Email Automatic Configuration 8 draft-jones-webfinger-email-autoconfig-00 10 Abstract 12 This document describes procedures for automatically configuring an 13 email client by using WebFinger to convey mail server configuration 14 and security-related information. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on January 9, 2020. 33 Copyright Notice 35 Copyright (c) 2019 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Conventions Used in This Document . . . . . . . . . . . . . . 2 52 3. Example User Scenario . . . . . . . . . . . . . . . . . . . . 3 53 4. Email Auto-Configuration Procedures . . . . . . . . . . . . . 5 54 4.1. Initiating a WebFinger Query . . . . . . . . . . . . . . 5 55 4.2. Processing the JSON Resource Descriptor . . . . . . . . . 5 56 4.3. Requesting the Email Configuration Document . . . . . . . 5 57 5. Email Configuration Document Syntax . . . . . . . . . . . . . 6 58 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 59 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 60 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 61 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 9.1. Normative References . . . . . . . . . . . . . . . . . . 6 63 9.2. Informative References . . . . . . . . . . . . . . . . . 6 64 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 67 1. Introduction 69 Configuring email clients manually can be a time-consuming and 70 mundane task that can actually be fairly arduous as the number of 71 users or clients increases. While people with technical 72 understanding of the various protocols and settings employed can 73 configure a single email client fairly easily, the task can prove 74 challenging and frustrating for non-technical users. 76 This document defines procedures utilizing WebFinger [RFC7033] that 77 make it trivial for end-users to configure email clients with little 78 or no assistance and with minimal technical skill. All that is 79 required for the user to do is enter his or her account identifier, 80 select an email account, and provide credentials. 82 Following these procedures, the complexity of configuring an email 83 client is shifted away from the end-user and pushed onto the software 84 tools that implement these procedures and the email administrators 85 who would have to configure the settings for each user server-side 86 and publish the required configuration data. However, the 87 configuration data can be generated with automated tools, meaning 88 there would be minimal effort for the email administrators. 90 2. Conventions Used in This Document 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 3. Example User Scenario 100 To illustrate how the procedures work, assume Alice just got a new 101 computer and installed her favorite email client. She is using 102 services from Example Mail Corporation and she was told her account 103 identifier is "alice@mail.example" and her password is "abc123". She 104 actually has two different accounts with Example Mail Corporation, 105 one for personal use and one for her business. The accounts are 106 aptly named "Personal" and "Business". 108 When Alice starts her email client and adds a new email account, the 109 client will ask her for her account identifier. She will then enter 110 "alice@mail.example", at which point the client will initiate a 111 WebFinger query to the host "mail.example". That HTTP [RFC7230] 112 query will look something like this: 114 GET /.well-known/webfinger?resource=acct%3Aalice%40mail.example \ 115 HTTP/1.1 116 Host: mail.example 118 (The backslash character '\' is there only to indicate the following 119 line is part of the same line.) 121 As per the WebFinger specification, a JSON Resource Descriptor (JRD) 122 will be returned with a number of different entires. For brevity, 123 the following reply shown excludes most of the content that is not 124 applicable to this example. The reply might look like this: 126 HTTP/1.1 200 OK 127 Access-Control-Allow-Origin: * 128 Content-Type: application/jrd+json 130 { 131 "subject" : "acct:alice@mail.example", 132 "links" : 133 [ 134 { 135 "rel" : "email-autoconfig", 136 "href" : "https://mail-config.mail.example/alice.personal.json" 137 "titles" : 138 { 139 "en-us" : "Personal" 140 } 141 }, 142 { 143 "rel" : "email-autoconfig", 144 "href" : "https://mail-config.mail.example/alice.business.json" 145 "titles" : 146 { 147 "en-us" : "Business" 148 }, 149 } 150 ] 151 } 153 Noting there are two "email-autoconfig" entries in the response, one 154 named "Personal" and one named "Business", Alice's email client will 155 prompt her to select one of the email accounts to configure to 156 provide a password. She selects the one named "Personal", at which 157 point the email client will issue a subsequent HTTP query to the URI 158 associated with that account: 160 GET /alice.personal.json HTTP/1.1 161 Host: mail-config.mail.example 163 The server "mail-config.mail.example" might require her to 164 authenticate using the password for her email account, which is why 165 she was prompted for it when selecting the account. Once the email 166 client satisfies whatever authentication challenge it is presented, 167 the server will then respond with a JSON document that contains all 168 of the configuration information necessary for the email client to 169 self-provision her "Personal" account. That reply might look 170 something like this: 172 HTTP/1.1 200 OK 173 Access-Control-Allow-Origin: * 174 Content-Type: application/jrd+json 176 { 177 "address" : "alice.i.wonder@mail.example", 178 "smtp" : 179 { 180 "login" : "alice.i.wonder", 181 "host" : "outbound.mail.example", 182 "port" : 587, 183 "login-required" : true, 184 "transport" : "starttls" 185 }, 186 "imap" : 187 { 188 "login" : "alice.i.wonder", 189 "host" : "imap.mail.example", 190 "port" : 143, 191 "transport" : "starttls" 192 } 193 } 195 The email client would utilize this information to configure itself 196 to access the mail server using SMTP and IMAP. The email client 197 would reasonably assume that the account password provided is the 198 same password used with both of those protocols. While that might 199 not be correct, it certainly simplifies the user's life if it is the 200 same. However, authentication may be via a digital certificate, for 201 example, conveyed in this response document. 203 4. Email Auto-Configuration Procedures 205 TBD 207 4.1. Initiating a WebFinger Query 209 TBD 211 4.2. Processing the JSON Resource Descriptor 213 TBD 215 4.3. Requesting the Email Configuration Document 217 TBD 219 5. Email Configuration Document Syntax 221 TBD 223 6. Security Considerations 225 TBD 227 7. IANA Considerations 229 TBD 231 We will need to register "email-autoconfig" in the Link Relations 232 registry: https://www.iana.org/assignments/link-relations/link- 233 relations.xhtml [1] 235 8. Acknowledgments 237 TBD 239 9. References 241 9.1. Normative References 243 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 244 Requirement Levels", BCP 14, RFC 2119, 245 DOI 10.17487/RFC2119, March 1997, 246 . 248 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 249 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 250 2013, . 252 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 253 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 254 May 2017, . 256 9.2. Informative References 258 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 259 Protocol (HTTP/1.1): Message Syntax and Routing", 260 RFC 7230, DOI 10.17487/RFC7230, June 2014, 261 . 263 9.3. URIs 265 [1] https://www.iana.org/assignments/link-relations/link- 266 relations.xhtml 268 Authors' Addresses 270 Paul E. Jones 271 Cisco 272 7025 Kit Creek Rd. 273 Research Triangle Park, North Carolina 27709 274 USA 276 Phone: +1 919 476 2048 277 Email: paulej@packetizer.com 279 Gonzalo Salgueiro 280 Cisco 281 7025 Kit Creek Rd. 282 Research Triangle Park, North Carolina 27709 283 USA 285 Phone: +1 919 392 3266 286 Email: gsalguei@cisco.com