// vim: ts=4 sw=4 et ft=asciidoc

[[muaconf]]
== How does auto config work?

Modern email clients (Mail User Agents) can look for configuration data when a user begins to create a new account.
They will either send the user's mail address to a service and ask the service to reply with configuration that suits the user's profile, or they will query the DNS system for advice.

Using a specialized mail account configuration service allows for individualized setups.
It also allows to enforce a specific policy, which for example configures the mail client to use a specific authentication mechanism.
Quering the DNS for mail service locations allows for generic instructions, but it doesn't give as much control over settings as a specialized service like automx2 will do.

As of today, there are four methods that help configuring a mail account.
Three of them – <<autoconfig>>, <<autodiscover>> and <<mobileconfig>>
– have been developed by vendors to cover their products' specific needs.
The fourth is an RFC standard specifying the aformentioned more general <<dnsrr>>
method.

The vendor specific methods have in common that the mail client seeking configuration needs to send a request, which includes at least the user's mail address, to a configuration service.
The service will use the mail address to lookup configuration data and will return that data as response to the client.
Format – XML response or file – and complexity differ depending on the method.

automx2 implements everything necessary to configure email accounts.
Functionality to configure calendar or address book settings is not included.
This may change in some future version, but the focus of automx2 is email.

[[autoconfig]]
=== Autoconfig

Autoconfig is a proprietary method developed by the Mozilla foundation.
It was designed to configure a mail account within Thunderbird, and other email suites like Evolution and KMail
link:https://wiki.mozilla.org/Thunderbird:Autoconfiguration:ConfigFileFormat[have adopted] the mechanism.

When a user begins to create a new mail account she is asked to enter her realname and mail address, e.g. _alice@example.com_.
Thunderbird will then extract the domainpart (_example.com_) from the mail address and build a list of URIs to search for a configuration web service in the following order:

[source,text]
[.small]
----
https://autoconfig.thunderbird.net/v1.1/example.com
https://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=alice@example.com
https://example.com/.well-known/autoconfig/mail/config-v1.1.xml
http://autoconfig.thunderbird.net/v1.1/example.com
http://autoconfig.example.com/mail/config-v1.1.xml?emailaddress=alice@example.com
http://example.com/.well-known/autoconfig/mail/config-v1.1.xml
----

A configuration service such as automx2 listening on one of the listed URIs will receive the request, process it and respond with a set of configuration instructions.

Thunderbird will use the instructions to automatically fill in the required fields in the account.
The only remaining task for the user is to confirm the settings.
After that she can immediately start to use her new mail account.

[[autodiscover]]
=== Autodiscover

Autodiscover is a proprietary method developed by Microsoft.
The protocol version supported by automx2 was designed to configure a mail account within Outlook 2016 ff.
Service lookups use the URLs shown below and, as a fallback option, DNS lookups.
Please note that Microsft uses a different autodiscover mechanism for Office 365, which is not yet supported by automx2 because information about the technical details are not available free of charge.

[source,text]
[.small]
----
https://example.com/autodiscover/autodiscover.xml
https://autodiscover.example.com/autodiscover/autodiscover.xml
http://autodiscover.example.com/autodiscover/autodiscover.xml

dns: autodiscover.example.com
dns: _autodiscover._tcp.example.com
----

All HTTP(S) queries send a POST request and submit XML which contains information about the account that should be configured.
The DNS queries search for a `CNAME` resource record first, which is supposed to redirect the mail client to a resource outside the mailbox owners domain, e.g. _alice@example.com_ would be redirected to `service.example-provider.com` for configuration instructions.
If the first DNS query fails the client may be redirected to a configuration service using a `SRV` RR like this:

[source,bind]
[.small]
----
_autodiscover._tcp.example.com.  0   443 service.example-provider.com.
----

The `SRV` RR used in the example above would send Alice's client to
`service.example-provider.com` and tell it to send the query to the configuration service on port `443`.

[[mobileconfig]]
=== Mobileconfig

Requests and responses use proprietary content types with an underlying link:https://en.wikipedia.org/wiki/Property_list[property list] format.
automx2 will return _unsigned_ data, which means that the service must be accessed via HTTPS only.
Otherwise, your users have no way of knowing if they access the correct service and will be vulnerable to man-in-the-middle attacks.

[[dnsrr]]
=== DNS SRV resource records

[source,bind]
[.small]
----
_imap._tcp.example.com          SRV  10  20  143  mail.example.com.
_imaps._tcp.example.com         SRV  0   1   993  .
_pop3._tcp.example.com          SRV  0   1   110  .
_pop3s._tcp.example.com         SRV  0   1   995  .
_smtp._tcp.example.com.         SRV  0   1   25   .
_submission._tcp.example.com.   SRV  10  20  587  mail.example.com.
----
