<?xml version="1.0" encoding="utf-8"?>
<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Processor - mmark.nl" -->
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' []>
<rfc ipr="trust200902" submissionType="IETF" category="std" xml:lang="en" consensus="yes" docName="draft-jones-webfinger-email-autoconfig-00">
<?rfc toc="yes"?><?rfc symrefs="yes"?><?rfc sortrefs="yes"?><?rfc compact="yes"?><?rfc subcompact="no"?><?rfc comments="no"?>
<front>
<title abbrev="WebFinger Email Autoconfigiguration">WebFinger Email Automatic Configuration</title><author initials="P." surname="Jones" fullname="Paul E. Jones"><organization>Cisco</organization><address><postal><street>7025 Kit Creek Rd.</street>
<city>Research Triangle Park</city>
<code>27709</code>
<country>USA</country>
<region>North Carolina</region>
</postal><phone>+1 919 476 2048</phone>
<email>paulej@packetizer.com</email>
</address></author>
<author initials="G." surname="Salgueiro" fullname="Gonzalo Salgueiro"><organization>Cisco</organization><address><postal><street>7025 Kit Creek Rd.</street>
<city>Research Triangle Park</city>
<code>27709</code>
<country>USA</country>
<region>North Carolina</region>
</postal><phone>+1 919 392 3266</phone>
<email>gsalguei@cisco.com</email>
</address></author>
<date/>
<area>Internet</area><workgroup></workgroup><keyword>WebFinger</keyword>
<keyword>Email Auto-configuration</keyword>
<keyword>Email Autoconfigiguration</keyword>
<keyword>Email Autoconfig</keyword>

<abstract><t>This document describes procedures for automatically configuring
an email client by using WebFinger to convey mail server configuration
and security-related information.</t>
</abstract>

</front>

<middle>

<section anchor="introduction" title="Introduction">
<t>Configuring email clients manually can be a time-consuming and mundane
task that can actually be fairly arduous as the number of users or clients
increases.  While people with technical understanding of the various
protocols and settings employed can configure a single email client fairly
easily, the task can prove challenging and frustrating for non-technical
users.</t>
<t>This document defines procedures utilizing WebFinger <xref target="RFC7033"></xref> that make it
trivial for end-users to configure email clients with little or no assistance
and with minimal technical skill.  All that is required for the user to do is
enter his or her account identifier, select an email account, and provide
credentials.</t>
<t>Following these procedures, the complexity of configuring an email client
is shifted away from the end-user and pushed onto the software tools
that implement these procedures and the email administrators who would have
to configure the settings for each user server-side and publish the required
configuration data.  However, the configuration data can be generated
with automated tools, meaning there would be minimal effort for the
email administrators.</t>
</section>

<section anchor="conventions-used-in-this-document" title="Conventions Used in This Document">
<t>The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;,
&quot;SHALL NOT&quot;, &quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;,
&quot;NOT RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this document
are to be interpreted as described in BCP 14 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref>
when, and only when, they appear in all capitals, as shown here.</t>
</section>

<section anchor="example-user-scenario" title="Example User Scenario">
<t>To illustrate how the procedures work, assume Alice just got a new computer
and installed her favorite email client.  She is using services from
Example Mail Corporation and she was told her account identifier is
&quot;alice@mail.example&quot; and her password is &quot;abc123&quot;.  She actually has two
different accounts with Example Mail Corporation, one for personal use and
one for her business.  The accounts are aptly named &quot;Personal&quot; and
&quot;Business&quot;.</t>
<t>When Alice starts her email client and adds a new email account, the client
will ask her for her account identifier.  She will then enter
&quot;alice@mail.example&quot;, at which point the client will initiate a WebFinger
query to the host &quot;mail.example&quot;.  That HTTP <xref target="RFC7230"></xref> query will look
something like this:</t>

<figure><artwork>  GET /.well-known/webfinger?resource=acct%3Aalice%40mail.example \
      HTTP/1.1
  Host: mail.example
</artwork></figure>

<t>(The backslash character '\' is there only to indicate the following line is
part of the same line.)</t>
<t>As per the WebFinger specification, a JSON Resource Descriptor (JRD) will be
returned with a number of different entires. For brevity, the following reply
shown excludes most of the content that is not applicable to this example.
The reply might look like this:</t>

<figure><artwork>  HTTP/1.1 200 OK
  Access-Control-Allow-Origin: *
  Content-Type: application/jrd+json

  {
    &quot;subject&quot; : &quot;acct:alice@mail.example&quot;,
    &quot;links&quot; :
    [
      {
        &quot;rel&quot; : &quot;email-autoconfig&quot;,
        &quot;href&quot; : &quot;https://mail-config.mail.example/alice.personal.json&quot;
        &quot;titles&quot; :
        {
          &quot;en-us&quot; : &quot;Personal&quot;
        }
      },
      {
        &quot;rel&quot; : &quot;email-autoconfig&quot;,
        &quot;href&quot; : &quot;https://mail-config.mail.example/alice.business.json&quot;
        &quot;titles&quot; :
        {
          &quot;en-us&quot; : &quot;Business&quot;
        },
      }
    ]
  }
</artwork></figure>

<t>Noting there are two &quot;email-autoconfig&quot; entries in the response, one named
&quot;Personal&quot; and one named &quot;Business&quot;, Alice's email client will prompt her
to select one of the email accounts to configure to provide a password.
She selects the one named &quot;Personal&quot;, at which point the email client will
issue a subsequent HTTP query to the URI associated with that account:</t>

<figure><artwork>   GET /alice.personal.json HTTP/1.1
  Host: mail-config.mail.example
</artwork></figure>

<t>The server &quot;mail-config.mail.example&quot; might require her to authenticate
using the password for her email account, which is why she was prompted
for it when selecting the account.  Once the email client satisfies
whatever authentication challenge it is presented, the server will then
respond with a JSON document that contains all of the configuration
information necessary for the email client to self-provision her &quot;Personal&quot;
account.  That reply might look something like this:</t>

<figure><artwork>  HTTP/1.1 200 OK
  Access-Control-Allow-Origin: *
  Content-Type: application/jrd+json

  {
    &quot;address&quot; : &quot;alice.i.wonder@mail.example&quot;,
    &quot;smtp&quot; :
    {
      &quot;login&quot; : &quot;alice.i.wonder&quot;,
      &quot;host&quot; : &quot;outbound.mail.example&quot;,
      &quot;port&quot; : 587,
      &quot;login-required&quot; : true,
      &quot;transport&quot; : &quot;starttls&quot;
    },
    &quot;imap&quot; :
    {
      &quot;login&quot; : &quot;alice.i.wonder&quot;,
      &quot;host&quot; : &quot;imap.mail.example&quot;,
      &quot;port&quot; : 143,
      &quot;transport&quot; : &quot;starttls&quot;
    }
  }
</artwork></figure>

<t>The email client would utilize this information to configure itself to
access the mail server using SMTP and IMAP.  The email client would
reasonably assume that the account password provided is the same
password used with both of those protocols.  While that might not be
correct, it certainly simplifies the user's life if it is the same.
However, authentication may be via a digital certificate, for example,
conveyed in this response document.</t>
</section>

<section anchor="email-auto-configuration-procedures" title="Email Auto-Configuration Procedures">
<t>TBD</t>

<section anchor="initiating-a-webfinger-query" title="Initiating a WebFinger Query">
<t>TBD</t>
</section>

<section anchor="processing-the-json-resource-descriptor" title="Processing the JSON Resource Descriptor">
<t>TBD</t>
</section>

<section anchor="requesting-the-email-configuration-document" title="Requesting the Email Configuration Document">
<t>TBD</t>
</section>
</section>

<section anchor="email-configuration-document-syntax" title="Email Configuration Document Syntax">
<t>TBD</t>
</section>

<section anchor="security-considerations" title="Security Considerations">
<t>TBD</t>
</section>

<section anchor="iana-considerations" title="IANA Considerations">
<t>TBD</t>
<t>We will need to register &quot;email-autoconfig&quot; in the Link Relations registry:
<eref target="https://www.iana.org/assignments/link-relations/link-relations.xhtml">https://www.iana.org/assignments/link-relations/link-relations.xhtml</eref></t>
</section>

<section anchor="acknowledgments" title="Acknowledgments">
<t>TBD</t>
</section>

</middle>

<back>
<references title="Normative References">
<?rfc include="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7033.xml"?>
<?rfc include="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
<?rfc include="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"?>
</references>
<references title="Informative References">
<?rfc include="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7230.xml"?>
</references>

</back>

</rfc>
