HowTo: automx and UCS

Knowledge Base Community
, , , , ,
#1

Published here hoping that it will be helpful to others. Comments or suggestions for improvement are highly appreciated.

@univention: Please check if the howto has the quality to be moved into the knowledge-base section. Or even better: If you can’t build it as an app.

HowTo: automx and UCS

Motivation: mail setup made easy for users!

  • automx runs on your UCS server and handles mail account profile requests from your mail clients
  • automx unifies Microsofts, Mozillas and Apples mail account provisioning standards in one powerful Open Source tool
  • It creates standard and individualized profiles on the fly, by using the information from the LDAP backend of UCS
  • Put an end to endless phone calls trying to coach users to configure settings, whose dialogs they can’t find
  • Stop wasting your time writing tutorials nobody reads

website: https://automx.org/en/
software: Release ANN: automx-0.10.2 released · sys4/automx · GitHub
install: https://github.com/sys4/automx/blob/2eb1c64bbb9a8497fc4bb35e7eaa286a0dfc3f38/INSTALL
tested with: UCS 4.2
Target audience: administrators of mail servers using UCS
Difficulty level: easy to medium
Time required: less than 30 minutes
Note: Of course except your time needed to setup the UCS server and implement the firewall/DNS changes and also for testing all the different mail clients: how long you need for this kind of work depends on your hardware and organizational structure.

Prerequisites

Aside from your mail server reachable from the internet, you will need an UCS member server and access to your DNS.

  • setup a tiny ucs member server and join to your UCS Domain as usual (no additional software needed during install)
  • make sure that port 80 and 443 of this server is accessible from the internet
  • create two DNS entries pointing to the UCS member server: (A or CNAME)
    autoconfig.<YourDomain>.de
    autodiscover.<YourDomain>.de
  • create a new user (simple authentication account) via UDM to grant automx access to the ldap
  • Optional, but highly recommended: install the univention app letsencrypt and setup a certificate for autoconfig.<YourDomain>.de and autodiscover.<YourDomain>.de
  • Optional, as an alternative to letsencrypt: Setup and use your own certificates

Note: It is technically possible to operate this setup without encryption, since no passwords have to be transmitted for the purpose of automatic configuration. However, I strongly recommend to use encrypted connections all the time, as this way, for example, configurations for Apple devices can also be signed. Letsencrypt will be used as CA in this howto.

Installation procedure

This posting contains step by step instructions to install automx.

Log in via ssh on the UCS member server and get root privileges.

ssh <user>@my-ucs-server.mydomain.tld
sudo -i

To simplify the installation, define some variables so that you can use the instructions given below by using copy&paste.
Do not use the example values given below. You have to adjust the values to your situation / domain. Please use your own username and passwords instead the example values!

export my_domain="belug.de"
export my_org="Belug e.V."
export automx_user="zzz___automx"
export automx_pwd="secret-password"
export my_mailserver="mail.${my_domain}"
export my_ldap_host="ldap://$(ucr get ldap/server/name):$(ucr get ldap/server/port), ldap://$(ucr get ldap/backup):$(ucr get ldap/server/port)"
export my_ldap_base="$(ucr get ldap/base)"
export my_external_automx_ip="217.197.83.32"

automx is a Python application. You must install a few extra modules/programs to handle frontend and backend communication as well to deal with XML data:
apt-get install -y git memcached libapache2-mod-wsgi python-sqlalchemy python-dateutil python-ipaddr python-lxml python-m2crypto

Download the software using git

mkdir -p /root/github/sys4 ; cd /root/github/sys4 
git clone https://github.com/sys4/automx.git
cd ./automx
git tag
git checkout tags/v0.10.2 # last stable release, python 2.7 compatible

Installing the program
Create a directory for the automx program and copy it to that location:

mkdir -p /usr/lib/automx
cp ./src/automx_wsgi.py /usr/lib/automx/

Installing the test program
cp ./src/automx-test /usr/bin/automx-test

Installing automx-specific libraries
cp -r ./src/automx /usr/lib/python2.7/

Installing man pages
cp -a ./doc/man/ /usr/local/man

Optional: Installing the Apple configuration webpage
cp -a html/ /var/www/apple
If you like, you can change the look of the website to suit your company/organization by changing the /var/www/apple/img/company-banner.png file.

Installing the configuration file
Follow automx.conf(5) Adopt this configuration file to your needs. You may find
detailed information in the man page automx.conf(5).

cat << EOF > /etc/automx.conf
[automx]
provider = ${my_domain}
domains = *

debug = yes
# debug log --> see /var/log/apache2/error.log

# Protect against DoS
memcache = 127.0.0.1:11211
memcache_ttl = 600
client_error_limit = 20
rate_limit_exception_networks = 127.0.0.0/8, ::1/128

# The DEFAULT section is always merged into each other section. Each section
# can overwrite settings done here.
[DEFAULT]
action = settings

account_type = email
account_name = ${my_org} - \${title} \${givenName} \${sn}
account_name_short =  ${my_org} (\${uid})
display_name = \${displayName}

smtp = yes
smtp_server = ${my_mailserver}
smtp_port = 465
smtp_encryption = ssl
smtp_auth_identity = \${uid}
smtp_auth = plaintext
smtp_refresh_ttl = 6
smtp_default = yes

imap = yes
imap_server = ${my_mailserver}
imap_port = 143
imap_encryption = starttls
imap_auth_identity = \${uid}
imap_auth = plaintext
imap_refresh_ttl = 6

pop = no

host = ${my_ldap_host}
base = ${my_ldap_base}
result_attrs = uid, title, displayName, givenName, sn
scope = sub
filter = (&(objectClass=*)(mailPrimaryAddress=%s))

binddn = uid=${automx_user},cn=users,${my_ldap_base}
bindpw = ${automx_pwd}
bindmethod = simple

sign_mobileconfig = yes
sign_cert = /etc/univention/letsencrypt/chained.pem
sign_key = /etc/univention/letsencrypt/domain.key

# If a domain is listed in the automx section, it may have its own section. If
# none is found here, the global section is used.
[global]
backend = ldap
action = settings
EOF

Optional: Setup letsencrypt
Skip this step if you already configured this via app as recommended in the beginning

univention-app update
univention-app install letsencrypt
ucr set letsencrypt/services/apache2=yes
ucr set hosts/static/${my_external_automx_ip}=autoconfig.${my_domain}
ucr set hosts/static/${my_external_automx_ip}=autodiscover.${my_domain}
ucr set letsencrypt/domains="autoconfig.${my_domain} autodiscover.${my_domain}"
/usr/share/univention-letsencrypt/setup-letsencrypt
service apache2 restart

Force the use of https, exclude autoconfig
Mozilla is using a not encrypted connection by default, so we have to exclude forcing https for this domain

ucr set apache2/force_https/exclude/http_host/autoconfig="autoconfig.${my_domain}" 
ucr set apache2/force_https=yes
ucr set apache2/ssl/honorcipherorder=yes
ucr set apache2/ssl/ciphersuite='HIGH:!aNULL:!MD5:-3DES:!CAMELLIA:-AES128:-RSA:AES128-SHA:AES128-SHA256:AES128-GCM-SHA256:DES-CBC3-SHA'
ucr set apache2/ssl/tlsv11=yes
ucr set apache2/hsts=yes
ucr set apache2/hsts/max-age=15768000
service apache2 restart

Setup the Apache config for the automx wsgi script

cat << EOF > /etc/apache2/sites-available/automx.conf
# autoconfig and autodiscover

  <Directory /usr/lib/automx>
    Require all granted
  </Directory>

  <IfModule mod_wsgi.c>
    WSGIScriptAlias /mail/config-v1.1.xml /usr/lib/automx/automx_wsgi.py
    WSGIScriptAlias /Autodiscover/Autodiscover.xml /usr/lib/automx/automx_wsgi.py
    WSGIScriptAlias /autodiscover/autodiscover.xml /usr/lib/automx/automx_wsgi.py
    WSGIScriptAlias /mobileconfig /usr/lib/automx/automx_wsgi.py
  </IfModule>
EOF

a2ensite automx
service apache2 restart

Test of automx

  • ldap connectivity test via cmdline: (change the mail adress used in the search filter to one of yours)
test_mailaddr="lutz.willek@belug.de"
ldapsearch -H ldap://$(ucr get ldap/server/name):$(ucr get ldap/server/port) -b ${my_ldap_base} -s sub -D uid=${automx_user},cn=users,${my_ldap_base} -w ${automx_pwd} -LLL "(&(objectClass=*)(mailPrimaryAddress=${test_mailaddr}))" uid title displayName givenName sn

Expected output similar to:

 dn: uid=lutz,cn=users,dc=belug,dc=de
 uid: lutz
 title: Herr
 sn: Willek
 givenName: Lutz
 displayName: Lutz Willek
  • via cmdline: automx-test ${test_mailaddr} (check output, in case of errors check /var/log/apache2/error.log file)
  • by simply setup a mail account and using Thunderbird
  • by simply setup a mail account and using Outlook 2013 or Outlook 2016
  • by simply using a IOS device and the url https://autoconfig.${my_domain}/apple (result should be signed)

If everything is fine please change debug to no in file /etc/automx.conf.

1 Like
#2
Mastodon