Adding upstream version 1:2.3.21+dfsg1.upstream/1%2.3.21+dfsg1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/wiki/AuthDatabase.LDAP.PasswordLookups.txt b/doc/wiki/AuthDatabase.LDAP.PasswordLookups.txt
new file mode 100644
index 0000000..a9232d5
--- /dev/null
+++ b/doc/wiki/AuthDatabase.LDAP.PasswordLookups.txt
@@ -0,0 +1,98 @@
+Passdb LDAP with password lookups
+=================================
+
+Advantages over <authentication binds> [AuthDatabase.LDAP.AuthBinds.txt]:
+
+ * Faster, because Dovecot can keep sending multiple LDAP requests
+   asynchronously to the server. With auth binds Dovecot must wait for each
+   request to finish before sending the next one.
+ * Supports non-plaintext <authentication mechanisms>
+   [Authentication.Mechanisms.txt] (if returning plaintext/ <properly hashed
+   passwords> [Authentication.PasswordSchemes.txt]).
+ * When using <LDA.txt> and static userdb, deliver can check if destination
+   user exists. With auth binds this check isn't possible.
+
+LDAP server permissions
+-----------------------
+
+Normally LDAP server doesn't give anyone access to users' passwords, so you'll
+need to create an administrator account that has access to the userPassword
+field. With OpenLDAP this can be done by modifying '/etc/ldap/slapd.conf':
+
+---%<-------------------------------------------------------------------------
+# there should already be something like this in the file:
+access to attribute=userPassword
+        by dn="<dovecot's dn>" read  # just add this line
+        by anonymous auth
+        by self write
+        by * none
+---%<-------------------------------------------------------------------------
+
+Replace <dovecot's dn> with the DN you specified in 'dovecot-ldap.conf's' 'dn'
+setting.
+
+Dovecot configuration
+---------------------
+
+The two important settings in password lookups are:
+
+ * 'pass_filter' specifies the LDAP filter how user is found from the LDAP. You
+   can use all the normal <variables> [Variables.txt] like '%u' in the filter.
+ * 'pass_attrs' specifies a comma-separated list of attributes that are
+   returned from the LDAP. If you set it to empty, all the attributes are
+   returned.
+
+Usually the LDAP attribute names aren't the same as <the field names that
+Dovecot uses internally> [PasswordDatabase.txt]. You must create a mapping
+between them to get the wanted results. This is done by listing the fields as
+'<ldap attribute>=<dovecot field>'. For example:
+
+---%<-------------------------------------------------------------------------
+pass_attrs = uid=user, userPassword=password
+---%<-------------------------------------------------------------------------
+
+This maps the LDAP "uid" attribute to Dovecot's "user" field and LDAP's
+"userPassword" attribute to Dovecot's "password" field. These two fields should
+always be returned, but it's also possible to return other special <extra
+fields> [PasswordDatabase.ExtraFields.txt].
+
+Password
+--------
+
+Most importantly the 'pass_attrs' must return a "password" field, which
+contains the user's password. The next thing Dovecot needs to know is what
+format the password is in. If all the passwords are in same format, you can use
+'default_pass_scheme' setting in 'dovecot-ldap.conf' to specify it. Otherwise
+each password needs to be prefixed with "{password-scheme}", for example
+"{plain}plaintext-password". See <Authentication.PasswordSchemes.txt> for a
+list of supported password schemes.
+
+Username
+--------
+
+LDAP lookups are case-insensitive. Unless you somehow normalize the username,
+it's possible that a user logging in as "user", "User" and "uSer" are treated
+differently. The easiest way to handle this is to tell Dovecot to change the
+username to the same case as it's in the LDAP database. You can do this by
+returning "user" field in the 'pass_attrs', as shown in the above example.
+
+If you can't normalize the username in LDAP, you can alternatively lowercase
+the username in 'dovecot.conf':
+
+---%<-------------------------------------------------------------------------
+auth_username_format = %Lu
+---%<-------------------------------------------------------------------------
+
+Example
+-------
+
+A typical configuration would look like:
+
+---%<-------------------------------------------------------------------------
+auth_bind = no
+pass_attrs = uid=user, userPassword=password
+pass_filter = (&(objectClass=posixAccount)(uid=%u))
+default_pass_scheme = MD5
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)