automua: Email client configuration made easy

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 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:

A configuration service such as automua 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 is a proprietary method developed by Microsoft. The protocol version supported by automua was designed to configure a mail account within Outlook 2016. Service lookups use the URLs shown below and, as a fallback option, DNS lookups. Please note that Microsoft uses a different autodiscover mechanism for Office 365, which is not yet supported by automua because information about the technical details are not available free of charge.

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 of 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:

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.

Requests and responses use proprietary content types with an underlying property list format. automua 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.

automua has been released on Arch Linux AUR to simplify the installation and the setup. You would require the Arch Linux distribution for that end. The AUR helper yay is recommended.

automua requires Python version 3.7 or greater, ideally in the form of a virtual Python environment, to run. Check the python3 version like this:

Prepare the virtual environment for the automua web service, adjusting the installation path to your taste (automua itself does not care). The path /srv/http/automua will be used as an example throughout this documentation. The BASH shell commands below should work with any modern Linux distribution.

Next, make sure to either login as the user created above, or change to this user via the 'su' command. This is important to ensure the correct file permissions. Download the script that will download and setup your automua service:

Executing the setup script will create a Python virtual environment called .venv in the current directory.

Activate the virtual environment and install the latest automua release from PyPI. Make sure to pick the correct activation for your shell from the .venv/bin directory. This is an example for BASH:

To make configuration more convenient, automua supports Mozilla-style placeholders. For example, the string %EMAILADDRESS% in database records will be replaced with the email address specified during the query. While based on a proprietary feature of Autoconfig, automua also applies placeholders to Autodiscover and Mobileconfig responses.

The configuration file defines automua runtime behaviour and it specifies the backend automua should read mailbox account configuration data from.

During startup automua searches for runtime configuration instructions in the following locations. The first match will determine the configuration used.

To specify parameters and options automua uses an INI file syntax. The example configuration that ships with automua looks like this:

Place the content of the example configuration into one of the configuration locations automua looks for and adapt it to your needs. Then configure the database backend with data that suits your setup, as described below.

If you want to verify a vanilla installation of automua works, you can populate it with internal test data. Start automua as described in section Running automua and send the following request to populate your database:

This example assumes you are running automua on localhost listening on TCP port 4243, which is the suggested default port.

Once you have populated the database with sample data you can test if automua works. Use curl to send an account configuration request for user@example.com:

As shown in the example, make sure to quote the URL as necessary. Otherwise, your command shell might perform pattern matching for characters like the question mark ? (FISH does).

automua uses the SQLAlchemy toolkit to access databases. This allows a variety of databases, a.k.a. dialects, to be used, simply by defining the appropriate connection URL.

As mentioned in a previous section, you can use Alembic to create or upgrade your database. You need to start your first run using an empty database for this to work, because Alembic stores versioning information in said database. Database upgrades are based on this information. Follow the steps shown below, setting the RELEASE variable to the GitHub tag or release number of your choice.

Next, change the value for sqlalchemy.url in alembic.ini to match your automua configuration. Create an empty database unless you are using SQLite, in which case Alembic will create the database for you. The final steps are activating the automua virtual Python environment and invoke make.

You should see output similar to the following:

The following is an example for a OpenRC run script /etc/init.d/automua which I use for Gentoo Linux:

If you wish to override any of the settings, copy the following to /etc/conf.d/automua and uncomment/change variables according to your needs. This is purely optional.

If your system uses systemd you may want to deploy the following automua.service unit file from the contrib section and place it in /etc/systemd/system/automua.service:

Once you have installed the service you need to tell systemd to reload its list of available services:

It should now be able to tell you about a service named automua:

Next enable and start automua using the following command:

You should see automua enabled and running:

You are now ready to start testing automua, as described below.

While logged in as an unprivileged user, change into the installation directory and start the .venv/scripts/flask.sh launch script:

Now that automua is up and running, you need to configure the web server proxy that will receive requests from the outside and forwards them to automua.

The following example defines a HTTP server, which will listen for requests to both autoconfig.example.com and autodiscover.example.com. All requests will be forwarded to automua, which listens on TCP port 4243 in this example. Requests to /initdb are restricted to clients connecting from the local host. The proxy_set_header directives will cause NGINX to pass relevant data about incoming requests' origins.

The following example shows an Apache configuration similar to the one above. ProxyPreserveHost directives will cause apache to pass relevant data about incoming requests' origins.