Email Client Autoconfiguration

In a previous guide, I addressed using static files to set up automatic configuration of email clients for your Neth Server. Among the limitations of that method is that it doesn't work for iOS clients, nor for the Mail application on macOS.

Here, I’m going to cover installation of automx, a small web tool which will generate the same configuration information for Thunderbird and Outlook (and compatible client) users, and will also generate custom configuration files for your Apple users.

Caution: This module is in a pre-beta stage. It shouldn’t hurt anything, but may not behave as expected. If you notice unexpected behavior, let me know here and I’ll see what I can do.

Just as before, you’ll need to set a couple of DNS entries. Since every DNS host is different, I can’t walk you through the details of this, but you’ll need to set two records:

  • You’ll need to set a CNAME or A record for autoconfig.yourdomain pointing to your Neth server.
  • You’ll need to set a SRV record for _autodiscover._tcp.yourdomain pointing to 0 0 443 autoconfig.yourdomain.

You’ll need to update your TLS certificate to include a hostname of autoconfig.yourdomain, in addition to any other hostnames it may already include.

Now you’re ready to install automx. First, you’ll need to have my repo configured; see the wiki for instructions. Then simply install nethserver-automx:

yum --enablerepo=danb35 install nethserver-automx

At this point, if you’re only concerned about Thunderbird and Outlook, you’re done. Automx will listen for autoconfiguration queries from either of those clients and respond appropriately. But if you want to use automx for iOS/OSX mail, there’s some more work to do.

iOS/OSX Mail is configured by downloading and installing a profile, contained in a small file with an extension of .mobileconfig. Automx will generate these profiles, and optionally it will also cryptographically sign them. Signing the profiles is encouraged–your users’ devices will complain loudly before installing an un-signed profile.

In order to sign the .mobileconfig files, automx must have access to a trusted certificate and the corresponding private key. For security reasons, this should not be your main server certificate. Rather, you should have a separate certificate for just autoconfig.yourdomain. Create a directory at /etc/automx/, and place the full chain and private key files there as fullchain.pem and privkey.pem, respectively. Then, do:

config setprop automx SignMobileconfig enabled CertPath /etc/automx/fullchain.pem KeyPath /etc/automx/privkey.pem
signal-event nethserver-automx-update

Your automx installation is now configured to sign the .mobileconfig files

Now that your server will generate and sign the .mobileconfig files, you need to give your users a way to get those files. You’ll do that by giving them a web form into which they’ll enter their name, email address, and password, and click to download the profile. Automx provides such a form, or you can integrate your own into whatever web page you like.

To install the default form, simply run

yum --enablerepo=danb35 install automx-web

This package includes forms in English and German; you’ll need to choose which one you want to present to your users. To use the English form, do:

cd /usr/share/automx
ln -s index.html.en index.html

Now, when your users visit autoconfig.yourdomain, they’ll see a form that looks like this: (image pending)

If you don’t want the automx branding for your users, and/or you just want to put this into another page, you simply need to add the following HTML code:

      <form action="/mobileconfig" method="post">
	<input type="hidden" name="_mobileconfig" value="true" />
	<label for="emailaddress">Email address</label>
	<input name="emailaddress" id="emailaddress" type="email" placeholder=" (mandatory)">
	<label for="cn">Full name</label>
	  <input name="cn" id="cn" type="text" placeholder="John Doe (optional)">
	<label for="password">Password</label>
	  <input name="password" id="password" type="password" placeholder="Password (optional)">
	<input type="submit" value="Request configuration!" />

Of course, you can adjust styling, tool tips, etc. to suit your website. The look is up to you, but the input names have to stay the same.

  • Test, test, test
  • See if I can get LDAP working as expected
  • Integrate the .mobileconfig form into the server-manager (or, better yet, into the user-manager that doesn’t exist yet)
  • Figure out why signing .mobileconfig files isn’t including the full certificate chain in the profile. This is causing the profiles to be marked as “unverified”.
  • email_autoconfig_module.txt
  • Last modified: 2020/12/13 19:17
  • by Dan Brown