Created Using EGroupware Mail server with ActiveDirectory (markdown)

Using-EGroupware-Mail-server-with-ActiveDirectory.md

@@ -0,0 +1,187 @@
+## Install EGroupware Mail with Active Directory (ADS)
+> This tutorial assumes **you have a working EGroupware installation** which either just **authenticates with ActiveDirectory** or also **uses ADS for storing users, groups and memberships** (follow [this](https://github.com/EGroupware/egroupware/wiki/Using-EGroupware-Mail-server-with-ActiveDirectory#change-new-installed-empty-egroupware-to-use-active-directory) to create a new EGroupware instance using ActiveDirectory)
+
+> The stock EGroupware Mail server uses EGroupware's MariaDB or MySQL database for authentication and storing mail-attributes.
+
+* Install **egroupware-mail** Linux package, but do NOT configure it any further yet
+* If you're EGroupware version is just 21.1.20220408 you need to install the following patch (not necessary/working for newer versions!):
+```
+for patch in 68f7437cd04ed9a74aaa4c59520af428bc30a1c1 1a0dd6214e7836451e495ece37885f9e6dc8a8a6 22c42a8caff9a967f261c81a2efa3b5a881876da
+do
+    curl https://github.com/EGroupware/egroupware/commit/$path.patch | docker exec -i egroupware patch -p1 -d /usr/share/egroupware-sources
+done
+docker restart egroupware
+```
+* Create in ADS a user with name `dovecot` with a passwort, to be used as Doveadm master-user
+
+#### Following steps are only necessary if you use users, groups and memberships from ADS, not if you just authenticate with it
+* Login into Setup (https://example.org/egroupware/setup/) using admin and PW from /var/lib/egroupware/egroupware-docker-install.log
+* Go to [Edit current configuration] and change in **Periodic import from ADS or LDAP into EGroupware database**: What to import? to **users, groups and memberships** and **[Save]**
+* Go to [Edit current configuration] and click on [Inital import] to import all existing ADS users and groups. If everything went successfully, you should see at the end the following message:
+```
+Setting new incremental import time to: 20XX-XX-XX XX:XX:XX UTC (XXXXXXXXXX)
+
+Created XX, updated 0 and deleted 0 accounts, with 0 errors.
+```
+* Close the window/tab and configure under **How frequent should the import run?** the periodic import, eg. set **2 hours** and **[Save]**
+
+
+#### Configure ADS authentication for EGroupware Mail / Dovecot, which is configured for our SQL database by default:
+
+* go to `/etc/egroupware-mail/dovecot` which contains the Dovecot configuration
+* make the changes commented with **EGroupware authentication with LDAP/ADS**
+```
+root@ubuntu:/etc/egroupware-mail/dovecot# vi $(grep -rl 'EGroupware authentication with LDAP/ADS')
+
+conf.d/auth-master.conf.ext:
+# Dovecot master uses "dovecot" user and it's password
+passdb {
+  # EGroupware authentication with LDAP/ADS: change to driver = ldap and comment sql-master and uncomment ldap-master
+  driver = ldap
+  #args = /etc/dovecot/dovecot-sql-master.conf.ext
+  args = /etc/dovecot/dovecot-ldap-master.conf.ext
+  master = yes
+  result_success = continue
+}
+
+conf.d/auth-sql.conf.ext:
+# EGroupware authentication with LDAP/ADS: comment the full block
+#passdb {
+#  driver = sql
+#
+#  # Path for SQL configuration file, see example-config/dovecot-sql.conf.ext
+#  args = /etc/dovecot/dovecot-sql.conf.ext
+#}
+  
+# "prefetch" user database means that the passdb already provided the
+# needed information and there's no need to do a separate userdb lookup.
+# <doc/wiki/UserDatabase.Prefetch.txt>
+# EGroupware authentication with LDAP/ADS: comment the full block
+#userdb {
+#  driver = prefetch
+#}
+conf.d/10-auth.conf:
+#!include auth-system.conf.ext
+!include auth-sql.conf.ext
+# EGroupware authentication with LDAP/ADS: uncomment auth-ldap (leave auth-sql needed for userdb!)
+!include auth-ldap.conf.ext
+#!include auth-passwdfile.conf.ext
+#!include auth-checkpassword.conf.ext
+#!include auth-vpopmail.conf.ext
+#!include auth-static.conf.ext
+```
+* Then you need to configure your Active Directory domain-controller:
+```shell
+root@ubuntu:/etc/egroupware-mail/dovecot# vi dovecot-ldap.conf.ext
+# LDAP URIs to use. You can use this instead of hosts list. Note that this
+# setting isn't supported by all LDAP libraries.
+uris = ldaps://<domain-controler>:636
+
+# Distinguished Name - the username used to login to the LDAP server.
+# Leave it commented out to bind anonymously (useful with auth_bind=yes).
+dn = CN=Administrator,CN=Users,DC=<my-domain>,DC=...
+
+# Password for LDAP server, if dn is specified.
+dnpass = <password-of-user-specified-above>
+
+# Use TLS to connect to the LDAP server.
+#tls = no
+# TLS options, currently supported only with OpenLDAP:
+#tls_ca_cert_file =
+#tls_ca_cert_dir =
+#tls_cipher_suite =
+# TLS cert/key is used only if LDAP server requires a client certificate.
+#tls_cert_file =
+#tls_key_file =
+# Valid values: never, hard, demand, allow, try
+tls_require_cert = never
+
+# LDAP protocol version to use. Likely 2 or 3.
+ldap_version = 3
+
+# LDAP base. %variables can be used here.
+# For example: dc=mail, dc=example, dc=org
+base = CN=Users,DC=<my-domain>,DC=...
+
+# Filter for user lookup. Some variables can be used (see
+# https://doc.dovecot.org/configuration_manual/config_file/config_variables/
+# for full list):
+#   %u - username
+#   %n - user part in user@domain, same as %u if there's no domain
+#   %d - domain part in user@domain, empty if user there's no domain
+#pass_filter = (&(objectClass=posixAccount)(uid=%u))
+# ActiveDirectory
+pass_filter = (&(objectClass=user)(sAMAccountName=%u))
+
+root@ubuntu:/etc/egroupware-mail/dovecot# vi dovecot-ldap.conf.ext
+# EGroupware master configuration
+# includes ldap configuration and overwrites user_filter to only allow uid=dovecot
+
+!include dovecot-ldap.conf.ext
+
+# LDAP
+#pass_filter = (&(objectClass=posixAccount)(uid=%u)(uid=dovecot))
+# ActiveDirectory
+pass_filter = (&(objectClass=user)(sAMAccountName=%u)(sAMAccountName=dovecot))
+```
+* Reload Dovecot with: 
+```shell
+alias doveadm='docker exec -it egroupware-mail doveadm'
+doveadm reload
+```
+* Test the authentication using doveadm:
+```shell
+doveadm auth test <user>
+Password: <password-of-user>
+passdb: <user> auth succeeded
+extra fields:
+  user=<user>
+```
+* If the authentication does not work, check `doveadm log errors` to see why
+* Test authentication with Dovecot master user `dovecot`
+```shell
+doveadm auth test dovecot <master-password>
+passdb: dovecot auth succeeded
+extra fields:
+  user=dovecot
+
+doveadm auth test -M dovecot <user> NszrbCQWdhMqg4QQ
+passdb: <user> auth succeeded
+extra fields:
+  user=<user>
+  original_user=dovecot
+  auth_user=dovecot
+```
+* log into EGroupware using the admin user you created above
+* go to **Administration** and right click on the user himself and in the menu on **Mailaccount**
+* Change in **IMAP** tab under **IMAP administration**: 
+```
+Admin user: dovecot
+Password:   <password-you-used-for-creating-user-dovecot>
+```
+* Go to **Aliases+Forwards** tab anc check `Email account active`
+* Store the mail account
+* Go to Mail app and verify you can access the mailbox of the user
+* Log out and in again, to let EGroupware recognize the working mail account for all users
+* go to account list, mark all user-rows with valid email addresses, right click on them and choose from the menu **(de)activate mail accounts** > **activate**
+* continue with further EGroupware Mail configurations as outlined in our Wiki
+
+## Change a new installed (empty!) EGroupware to use Active Directory
+
+* **This tutorial assumes you just installed egroupware-docker** to get an empty EGroupware installation, as **it will delete all data**!
+* If you want to use EGroupware EPL, install it **after** switching to Active Directory, as this will remove all application run-rights
+* Login into Setup (https://example.org/egroupware/setup/) using admin and PW from /var/lib/egroupware/egroupware-docker-install.log
+* Go to [Edit current configuration] and change:
+
+    - In **Authentication/Accounts**: type of auth and where to store accounts to Active Directory
+    - In **If using ADS (Active Directory)**: fill out at least the first 4 fields (use the Administrator or another Domain Admin for now, as we need to create the required EGroupware groups "Admins", "Default", "NoGroup", "Teachers" and the user "anonymous"!)
+    - [Save] the configuration
+* if you see an error message in the "Setup main menu" or a red cross in front of [Create admin account], you need to fix your ADS configuration, **before** you can continue
+* Go to [Create admin account] and:
+
+    - check "Delete all existing SQL accounts, groups, ..."
+    - enter the details of an existing ADS account which is a member of "Domain Admin" group, who should become your first EGroupware Admins account using ```*unchanged*``` as password
+    - do NOT check the last two checkboxes
+* log out of Setup, click on "Back to user login" and log in with the ADS account and it's real password
+* now you can add all other EGroupware users to the newly created "Default" group, which is the EGroupware all users groups, please do NOT remove or rename it
+* further EGroupware Admins can be added to EGroupware's "Admins" group