Added documentation for Dovecot setup

doc/manual_installation/dovecot.rst

@@ -55,7 +55,7 @@ In order for dovecot to automaticaly create usual folders on account creation, e
 
 Starting dovecot 2.2.20+, you can add ``autoexpunge`` parameter to delete older message, for instance::
 
-    mailbox Trash {
+  mailbox Trash {
     auto = subscribe
     special_use = \Trash
     autoexpunge=30d
@@ -254,6 +254,50 @@ For debian and derivative, you need to install sqlite connector for dovecot::
 
    Replace values between ``<>`` with yours.
 
+OAuth 2 authentication
+======================
+
+You first need to register Dovecot as an authorized consumer of the
+OAuth2 authentication service provided by Modoboa. To do so, create an
+application with the following commands:
+
+.. sourcecode:: bash
+
+   > cd <modoboa_instance_path>
+   > python manage.py createapplication --name=Dovecot --algorithm=RS256 --skip-authorization --redirect-uris=http://localhost --client-secret=<client_secret> public authorization-code
+
+Choose a value for ``<client_secret>`` (you can generate a random one).
+
+On success, you should see an output similar to::
+
+  New application Dovecot created successfully.
+  client_secret: XXXX
+
+To enable OAuth2 authentication in Dovecot, edit the :file:`conf.d/10-auth.conf`
+file and add the following line at the end::
+
+  #!include auth-oauth2.conf.ext
+
+Then, create a file named :file:`conf.d/auth-oauth2.conf.ext` with the
+following content::
+
+  passdb {
+    driver = oauth2
+    mechanisms = xoauth2 oauthbearer
+    args = /etc/dovecot/conf.d/dovecot-oauth2.conf.ext
+  }
+
+Finally, create a file named :file:`conf.d/dovecot-oauth2.conf.ext` with the
+following content::
+
+  introspection_mode = post
+  introspection_url = http://<client_id>:<client_secret>@localhost/api/o/introspect/
+  username_attribute = username
+  tls_ca_cert_file = /etc/ssl/certs/ca-certificates.crt
+  active_attribute = active
+  active_value = true
+
+Replace ``<client_id>`` and ``<client_secret>`` with the values you obtained earlier.
 
 LDAP
 ====