Add guide how to setup ldap, imap and provisioning

Signed-off-by: Daniel Kesselberg <mail@danielkesselberg.de>

9 files changed, 138 insertions, 10 deletions

diff --git a/doc/developer.md b/doc/developer.md
index 6a9a55df3..5aea2cf74 100644
--- a/doc/developer.md
+++ b/doc/developer.md
@@ -1,15 +1,5 @@
 # Nextcloud Mail Developer Documentation
 
-## Nightly builds
-
-Instead of setting everything up manually, you can just [download the nightly builds](https://nightly.portknox.net/mail/?C=M;O=D) instead. These builds are updated every 24 hours, and are pre-configured with all the needed dependencies.
-
-1. Download
-2. Extract the tar archive to 'path-to-nextcloud/apps'
-3. Navigate to »Apps«, choose the category »Productivity«, find the Mail app and enable it.
-
-The nightly builds are provided by [Portknox.net](https://portknox.net)
-
 ## Resetting the app
 Connect to your database and run the following commands (`oc_` is the default table prefix):
 ```sql
@@ -27,3 +17,141 @@ DROP TABLE oc_mail_trusted_senders;
 DROP TABLE oc_mail_tags;
 DROP TABLE oc_mail_message_tags;
 ```
+
+## Testing LDAP aliases provisioning
+
+Testing the ldap aliases provisioning requires:
+
+1. LDAP service configured in Nextcloud
+2. IMAP service using LDAP for authentication
+3. A provisioning configuration for Mail
+
+### LDAP service configured in Nextcloud
+
+The fastest way to setup Nextcloud with LDAP is https://github.com/juliushaertl/nextcloud-docker-dev.
+
+It's still possible to integrate a ldap service into your own
+development setup with docker-compose.
+
+```
+ldap:
+  image: osixia/openldap:1.5.0
+  command: --copy-service --loglevel debug
+  ports:
+    - 50003:389
+  volumes:
+    - ./ldap:/container/service/slapd/assets/config/bootstrap/ldif/custom
+  environment:
+    LDAP_DOMAIN: planetexpress.com
+	LDAP_BASE_DN: dc=planetexpress,dc=com
+
+ldapadmin:
+  image: osixia/phpldapadmin:0.9.0
+  ports:
+    - 50004:443
+  environment:
+    - PHPLDAPADMIN_LDAP_HOSTS=ldap
+```
+
+To have sample users we are using https://github.com/juliushaertl/nextcloud-docker-dev/tree/master/data/ldap.
+- Download the directory and save it in the same directory as docker-compose.yml.
+- Delete 99_others.ldif (otherwise you have a lot of additional test users).
+- Adjust the port mapping for your use case if necessary.
+
+Run docker-compose to start ldap and ldapadmin.
+Visit ldapadmin at http://localhost:50004 (or whatever port you configured) and try to login with
+
+- user: cn=admin,dc=planetexpress,dc=com
+- password: admin
+
+![ldapadmin overview](./ldap_ldapadmin.png)
+
+Next step is to configure our LDAP service in Nextcloud.
+- Login as administrator
+- Go to apps and enable "LDAP user and group backend"
+- Go to settings -> LDAP/AD integration
+
+![ldap in nextcloud - server](./ldap_nc1.png)
+
+- Host: the address of your LDAP server
+- Port: 389 mostly
+- User DN: cn=admin,dc=planetexpress,dc=com
+- Password: admin
+- One Base DN per line: dc=planetexpress,dc=com
+
+Click Test Base DN to test the configuration.
+
+![ldap in nextcloud - user](./ldap_nc2.png)
+
+- Only these object classes: inetOrgPerson
+
+Click Verfiy settings and count users.
+
+![ldap in nextcloud - login attributes](./ldap_nc3.png)
+
+- Check LDAP/AD Username
+- Check LDAP/AD Email Address
+
+![ldap in nextcloud - groups](./ldap_nc4.png)
+
+- Only these object classes: groupOfNames
+
+![ldap in nextcloud - groups](./ldap_nc5.png)
+
+- User Display Name Field: givenName
+
+### IMAP service using LDAP for authentication
+
+In a production environment we would configure our IMAP service
+to authenticate against the LDAP service. For our testing scenario it's
+sufficient to configure some LDAP accounts on the IMAP service.
+
+```
+imap:
+  image: christophwurst/imap-devel:latest
+  ports:
+    - 25:25
+    - 143:143
+    - 993:993
+    - 4190:4190
+  environment:
+    - MAILNAME=mail.domain.tld
+    - MAIL_ACCOUNTS=admin@test.local,password 3268b904-582d-103b-83a5-c7ccb54ec103@planetexpress.com,bender 32657d7a-582d-103b-83a4-c7ccb54ec103@planetexpress.com,amy
+```
+
+Extend our docker-compose.yml and add the imap test image.
+Use the MAIL_ACCOUNTS environment variable to create test accounts for IMAP.
+
+
+![ldap in nextcloud - user management](./ldap_nc6.png)
+
+3268b904-582d-103b-83a5-c7ccb54ec103@planetexpress.com is the username for
+the user in the LDAP directory. The username might be different on your setup.
+Please lookup the right values in the Nextcloud user management.
+
+To create a IMAP account for Amy and Bender add to MAIL_ACCOUNTS.
+
+`32657d7a-582d-103b-83a4-c7ccb54ec103,amy 3268b904-582d-103b-83a5-c7ccb54ec103,bender`
+
+The password is (for our sample data) the display name in lowercase.
+Note that accounts are seperated by a space.
+
+### A provisioning configuration for Mail
+
+![ldap in nextcloud - provisioning configuration](./ldap_nc7.png)
+
+The above configuration will query the mailAlias attribute for each user
+and use it to create and delete aliases.
+
+Our sample data for LDAP does not contain mailAlias. To add one or more mailAliases
+to a user:
+- Visit ldapadmin
+- Expand dc=planetexpress,dc=com
+- Expand ou=people
+- Pick a user (e.g Bender)
+- Look for objectClass -> Click add value -> Select PostfixBookMailAccount -> Click Add new ObjectClass
+- Click Add new attribute -> Select mailAlias -> Enter rodriquez@planetexpress.com -> Press Enter -> Click Update Object
+
+Now login to Nextcloud as Bender and go to Mail. See rodriquez@planetexpress.com
+as Alias in the Account settings for the provisoned mail account.
+
diff --git a/doc/ldap_ldapadmin.png b/doc/ldap_ldapadmin.png
new file mode 100644
index 000000000..2c0d0b664
--- /dev/null
+++ b/doc/ldap_ldapadmin.png
diff --git a/doc/ldap_nc1.png b/doc/ldap_nc1.png
new file mode 100644
index 000000000..cba66a579
--- /dev/null
+++ b/doc/ldap_nc1.png
diff --git a/doc/ldap_nc2.png b/doc/ldap_nc2.png
new file mode 100644
index 000000000..d659328ed
--- /dev/null
+++ b/doc/ldap_nc2.png
diff --git a/doc/ldap_nc3.png b/doc/ldap_nc3.png
new file mode 100644
index 000000000..e55016bfe
--- /dev/null
+++ b/doc/ldap_nc3.png
diff --git a/doc/ldap_nc4.png b/doc/ldap_nc4.png
new file mode 100644
index 000000000..f30fddf00
--- /dev/null
+++ b/doc/ldap_nc4.png
diff --git a/doc/ldap_nc5.png b/doc/ldap_nc5.png
new file mode 100644
index 000000000..002a07f86
--- /dev/null
+++ b/doc/ldap_nc5.png
diff --git a/doc/ldap_nc6.png b/doc/ldap_nc6.png
new file mode 100644
index 000000000..a22c0f9e8
--- /dev/null
+++ b/doc/ldap_nc6.png
diff --git a/doc/ldap_nc7.png b/doc/ldap_nc7.png
new file mode 100644
index 000000000..e17f2e80d
--- /dev/null
+++ b/doc/ldap_nc7.png