"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "dovecot-1.0.15/doc/wiki/AuthDatabase.LDAP.txt" of archive dovecot-1.0.15.tar.gz:

    1 
    2 
    3 LDAP
    4 ====
    5 
    6 
    7 There are two ways to do LDAP authentication: password lookups and authentication binds. Both of these have their own advantages. 
    8 
    9 
   10 Password lookups
   11 ================
   12 
   13 
   14 This method is faster than authentication binds, because Dovecot needs to do only a single LDAP binding when the connection opens. After that it can keep sending LDAP requests asynchronously to the LDAP server. 
   15 Normally LDAP server doesn't give anyone access to users' userPassword field, so you'll need to configure some administrator account which has access to them (see >>HowTo/DovecotOpenLdap<< for general LDAP configuration examples). With OpenLDAP this can be done by modifying '/etc/ldap/slapd.conf': 
   16 
   17 ---%<-------------------------------------------------------------------------
   18 # there should already be something like this in the file:
   19 access to attribute=userPassword
   20         by dn="<dovecot's dn>" read  # just add this line
   21         by anonymous auth
   22         by self write
   23         by * none
   24 ---%<-------------------------------------------------------------------------
   25 
   26 Use the same dn in Dovecot's 'dn' setting. 
   27 The two important settings in password lookups are 'pass_filter' and 'pass_attrs'. 'pass_filter' specifies the LDAP filter how user is found from the LDAP. You can use all the normal >>variables<<  like '%u' in the filter. 'pass_attrs' specifies a list of attributes that are returned from the LDAP. If you set it to empty, all the attributes are returned. 
   28 'pass_attrs' is a comma separated list of '<ldap attribute>=<dovecot field>' fields. If '=<dovecot field>' is omitted, they're treated equal. For example 'userPassword=password' means that "userPassword" LDAP attribute contains Dovecot's "password" field. 
   29 Most importantly the 'pass_attrs' should 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' to specify it. Otherwise each password needs to be prefixed with "{password-scheme}", for example "{plain}plaintext-password". See >>Authentication/PasswordSchemes<< for a list of supported password schemes. 
   30 The next problem you have is that 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'. 
   31 Besides "user" and "password" fields, the 'pass_attrs' may contain also other special >>extra fields<<. 
   32 So a typical configuration would look like: 
   33 
   34 ---%<-------------------------------------------------------------------------
   35 auth_bind = no
   36 pass_attrs = uid=user,userPassword=password
   37 pass_filter = (&(objectClass=posixAccount)(uid=%u))
   38 default_pass_scheme = LDAP-MD5
   39 ---%<-------------------------------------------------------------------------
   40 
   41 
   42 
   43 Authentication binds
   44 ====================
   45 
   46 
   47 Authentication binds have two advantages: 
   48 
   49  1. The LDAP server verifies the password, so Dovecot doesn't need to know what format the password is in the LDAP server. 
   50  2. A bit more secure, as a security hole in Dovecot doesn't give attacker access to all the users' passwords. 
   51 The main downside is that it's somewhat slower because there can't be any LDAP requests pending while the binding is in progress. So the LDAP request queue is first flushed, then the binding to user is done, and finally binding is done back to the default DN before any userdb LDAP requests can be done. 
   52 Because of the above extra binding it can be slightly faster if you use separate LDAP connections for passdb and userdb. This can be done by specifying different filenames in passdb's and userdb's args. The files themselves can be identical or even symlinks to the same file, as long as the filename is different. 
   53 You can enable authentication binds by setting 'auth_bind=yes'. Next Dovecot needs to know what DN to use in the binding. There are two ways to configure this: passdb lookup or userdn template. 
   54 
   55 
   56 passdb lookup
   57 =============
   58 
   59 
   60 This is very similar to "Password lookups" described above, except that 'pass_attrs' doesn't need to return "password" field. The 'pass_filter' is used to find the LDAP entry, and the DN is taken from the reply. 
   61 Just as with password lookups, the 'pass_attrs' may contain special >>extra fields<<. 
   62 A typical configuration would look like: 
   63 
   64 ---%<-------------------------------------------------------------------------
   65 auth_bind = yes
   66 # returning "user" changes the username to be in same case as in LDAP database
   67 pass_attrs = uid=user
   68 pass_filter = (&(objectClass=posixAccount)(uid=%u))
   69 ---%<-------------------------------------------------------------------------
   70 
   71 
   72 
   73 userdn template
   74 ===============
   75 
   76 
   77 Using the userdn template is faster because it avoids one LDAP lookup. However with only IMAP/POP3 logins this can also be accomplished with prefetch userdb (see below). Then again if you're also using SMTP AUTH, or something else which doesn't do userdb lookup, this is again faster because no LDAP lookups need to be done. 
   78 If you're using userdn template, 'pass_attrs' and 'pass_filter' settings are completely ignored. That also means that you can't make passdb return any >>extra fields<<. 
   79 Note that all other examples have used 'pass_attrs = uid=user' to change username's case to same as in the LDAP database. This can't be done with userdn template, so you'll need to normalize the case some other way. The easiest way is to use 'auth_username_format = %Lu' in dovecot.conf to make the username always lowercased. 
   80 A typical configuration would look like: 
   81 
   82 ---%<-------------------------------------------------------------------------
   83 auth_bind = yes
   84 auth_bind_userdn = cn=%u,ou=people,o=org
   85 ---%<-------------------------------------------------------------------------
   86 
   87 
   88 
   89 User database lookups
   90 =====================
   91 
   92 
   93 Usually your LDAP database contains also the userdb information. This means user's UID, GID and home directory. If you're using only static UID and GID, and your home directory can be specified with a template, you could use >>static userdb<< instead. It is also a bit faster since it avoids doing the userdb LDAP lookup. 
   94 Userdb lookups are always done using the default DN ('dn' setting) binding. It's not possible to do the lookup using the user's DN (remember that eg. >>deliver<< needs to do userdb lookups without knowing the user's password). 
   95 The userdb lookups are configured in very much the same way as passdb lookups. 'user_filter' contains how to find the user entry (usually it's exactly the same as 'pass_filter'). 'user_attrs' contains a comma separated list of '<ldap attribute>=<dovecot field>' fields, just like described above for 'pass_attrs'. 
   96 The commonly returned userdb fields are uid, gid, home and mail. See >>UserDatabase/ExtraFields<< for more information about these and other fields that can be returned. 
   97 If you're using a single UID and GID for all the users, you can use 'user_global_uid' and 'user_global_gid' settings instead of of returning them from LDAP. 
   98 
   99 
  100 Connecting
  101 ==========
  102 
  103 
  104 You can specify one or more LDAP servers using 'hosts' or 'uris' settings. The URIs aren't supported by all the LDAP libraries. They're in format scheme://host:port, eg. ldap://localhost. 
  105 
  106 
  107 SSL/TLS
  108 =======
  109 
  110 
  111 If your LDAP library supports TLS, you can enable it by setting 'tls=yes'. FIXME: I'm not sure how the actual TLS configuration (certificates etc.) can be done. The OpenLDAP library reads some configuration files which can be used to do it. 
  112 Apparently it's also possible to use SSL by using ldaps scheme in the URI. 
  113 
  114 
  115 SASL binds
  116 ==========
  117 
  118 
  119 It's possible to use SASL binds if your LDAP library supports them. See the sasl_* settings in dovecot-ldap.conf. Note that SASL binds are currently incompatible with authentication binds. 
  120 
  121 
  122 Active Directory
  123 ================
  124 
  125 
  126 When connecting to AD, use port 3268. 
  127 
  128 
  129 Prefetching
  130 ===========
  131 
  132 
  133 If you want to avoid userdb lookups when logging in with IMAP/POP3, you can make the passdb lookup return all the necessary userdb fields and use prefetch userdb to use those fields. If you're using Dovecot's >>deliver<< you'll still need to have the userdb lookups working. 
  134 See >>UserDatabase/Prefetch<< for example configuration. 
  135 (This file was created from the wiki on 2007-12-11 04:42)