saslauthd/LDAP_SASLAUTHD

   1 auth_ldap module for saslauthd
   2 ------------------------------
   3
   4 Saslauthd can use an LDAP directory for authentication/authorization.
   5
   6 Sections:
   7 1. Build saslauthd with ldap support
   8 2. Start saslauthd with ldap
   9 3. Testing
  10 4. Parameters
  11 5. Examples
  12 6. Notes
  13 7. Todo
  14 8. Feedback
  15 8. Author
  16
  17
  18 1. BUILD SASLAUTHD WITH LDAP SUPPORT
  19 ------------------------------------
  20
  21 Ensure that you have the OpenLDAP (http://www.openldap.org) libraries 2.1 or
  22 higher.  Fetch the latest cyrus-sasl package, 2.1.17 or higher,
  23 ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/.
  24
  25 Unpack cyrus-sasl:
  26 gzip -dc cyrus-sasl-2.1.17.tar.gz | tar xf -
  27 or
  28 tar zxf cyrus-sasl-2.1.17.tar.gz (if your tar supportz gzip)
  29
  30 cd cyrus-sasl-2.1.17
  31 ./configure --with-ldap  (you may need to add other options, check doc/index.html for more)
  32 make
  33 make install
  34
  35
  36 2. START SASLAUTHD WITH LDAP
  37 ----------------------------
  38
  39 Create /usr/local/etc/saslauthd.conf and add the following (modify to fit your
  40 environment):
  41 ldap_servers: ldap://10.1.1.15/ ldap://10.1.1.25/
  42 ldap_bind_dn: cn=operator,ou=Profile,o=foo.com
  43 ldap_password: secret
  44
  45 Do not specify ldap_bind_*/ldap_password if you want to bind anonymously to
  46 your ldap server(s).
  47
  48 Run saslauthd:
  49 saslauthd -a ldap
  50
  51 If you want to specify a different configuration file, you can do something
  52 like:
  53 saslauthd -a ldap -O /etc/saslauthd.conf
  54
  55 For more command line options, check 'man saslauthd'
  56
  57
  58 3. TESTING
  59 ----------
  60
  61 First build testsaslauthd:
  62 cd $sasl_src/saslauthd
  63 make testsaslauthd
  64
  65 Run test utility:
  66 ./testsaslauthd -u igor -p secret
  67 0: OK "Success."
  68
  69 If you get output other then Success, turn debug level for the auth syslog
  70 facility and check the syslog file.  Hopefully this will give you enough
  71 information to make adjustements in the startup and/or configuration files.
  72
  73
  74 4. PARAMETERS
  75 -------------
  76
  77 The following are available ldap parameters.  There are quite a few of those,
  78 but only ldap_servers may need to be specified. The defaults for all other
  79 parameters are adequate for most installations.
  80
  81 Do not use quotes (\"\') in the parameter values.  The defaults are specified
  82 within the first set of <>.  There may be a second set of <> which provide
  83 available values.
  84
  85 ldap_auth_method: <bind|fastbind> <bind|custom|fastbind>
  86         Specify an authentication method.
  87
  88     The bind method uses the LDAP bind facility to verify the password.  The
  89     bind method is not available when ldap_use_sasl is turned on.  In that case
  90     saslauthd will use fastbind.
  91
  92     'bind' is the default auth method. When ldap_use_sasl is enabled,
  93     'fastbind' is the default.
  94
  95     The custom method uses userPassword attribute to verify the password.
  96     Suppored hashes: crypt, md5, smd5, sha and ssha.  Cleartext is supported as
  97     well.
  98
  99     The fastbind method (when 'ldap_use_sasl: no') does away with the search
 100     and an extra anonymous bind in auth_bind, but makes two assumptions:
 101           1. Expanding the ldap_filter expression gives the user's fully-qualified DN
 102           2. There is no cost to staying bound as a named user
 103
 104 ldap_bind_dn: <none>
 105         Specify DN (distinguished name) to bind to the LDAP directory.  Do not
 106         specify this parameter for the anonymous bind.
 107
 108 ldap_bind_pw: <none>
 109         Alias for ldap_password.
 110
 111 ldap_default_domain: <none>
 112         Alias for ldap_default_realm.
 113
 114 ldap_default_realm: <none>
 115         The default realm is assigned to the %r token when realm is not
 116         available.  See ldap_filter for more.
 117
 118 ldap_deref: <none> <search|find|always|never>
 119         Specify how aliases dereferencing is handled during search.
 120
 121 ldap_filter: <uid=%u>
 122         Specify a filter.  The following tokens can be used in the filter string:
 123
 124         %%   = %
 125         %u   = user
 126         %U   = user portion of %u (%U = test when %u = test@domain.tld)
 127         %d   = domain portion of %u if available (%d = domain.tld when %u =
 128                %test@domain.tld), otherwise same as %r
 129         %1-9 = domain tokens (%1 = tld, %2 = domain when %d = domain.tld)
 130         %s   = service
 131         %r   = realm
 132         %D   = user DN (available for group checks)
 133
 134         The %u token has to be used at minimum for the filter to be useful.  If
 135         ldap_auth_method is 'bind', the filter will search for the DN
 136         (distinguished name) attribute.  Otherwise, the search will look for
 137         the 'ldap_password_attr' (see below) attribute.
 138
 139 ldap_group_attr: <uniqueMember>
 140     Specify what attribute to compare the user DN against in the group. If
 141     ldap_group_dn is not specified, this parameter is ignored.  If
 142     ldap_group_match_method is not attr, this parameter is ignored.
 143
 144 ldap_group_dn: <none>
 145     If specified, the user has to be part of the group in order to authenticate
 146     successfully.  Tokens described in 'ldap_filter' (see above) can be used
 147     for substitution.
 148
 149 ldap_group_filter: <none>
 150     Specify a filter. If a filter match is found then the user is in the group.
 151     Tokens described in 'ldap_filter' (see above) can be used for for
 152     substitution. If ldap_group_dn is not specified, this parameter is ignored.
 153     If ldap_group_match_method is not filter, this parameter is ignored.
 154
 155 ldap_group_match_method: <attr> <attr|filter>
 156     Specify whether the group match method uses ldap_group_attr or
 157     ldap_group_search.  If ldap_group_dn is not specified, this parameter is
 158     ignored.
 159
 160 ldap_group_search_base: <if not specified, it defaults to ldap_search_base>
 161     Specify a starting point for the group search: e.g. dc=foo,dc=com.  Tokens
 162     described in 'ldap_filter' (see below) can be used for substitution.
 163
 164 ldap_group_scope: <sub> <sub|one|base>
 165         Group search scope.
 166
 167 ldap_password: <none>
 168         Specify the password for ldap_bind_dn or ldap_id if
 169         ldap_use_sasl is turned on.  Do not specify this parameter for the
 170         anonymous bind.
 171
 172 ldap_password_attr: <userPassword>
 173         Specify what password attribute to use for password verification.
 174
 175 ldap_referrals: <no>
 176         Specify whether or not the client should follow referrals.
 177
 178 ldap_restart: <yes>
 179         Specify whether or not LDAP I/O operations are automatically restarted
 180         if they abort prematurely.
 181
 182 ldap_id: <none>
 183         Specify the authentication ID for SASL bind.
 184
 185 ldap_authz_id: <none>
 186         Specify the proxy authorization ID for SASL bind.
 187
 188 ldap_mech: <none>
 189         Specify the authentication mechanism for SASL bind.
 190
 191 ldap_realm: <none>
 192         Specify the realm of authentication ID for SASL bind.
 193
 194 ldap_scope: <sub> <sub|one|base>
 195         Search scope.
 196
 197 ldap_search_base: <none>
 198         Specify a starting point for the search: e.g. dc=foo,dc=com.  Tokens
 199         described in 'ldap_filter' (see below) can be used for substitution.
 200
 201 ldap_servers: <ldap://localhost/>
 202         Specify URI(s) refering to LDAP server(s), e.g. ldaps://10.1.1.2:999/.
 203         You can specify multiple servers separated by a space.
 204
 205 ldap_start_tls: <no>
 206         Use StartTLS extended operation.  Do not use ldaps: ldap_servers when
 207         this option is turned on.
 208
 209 ldap_time_limit: <5>
 210         Specify a number of seconds for a search request to complete.
 211
 212 ldap_timeout: <5>
 213         Specify a number of seconds a search can take before timing out.
 214
 215 ldap_tls_check_peer: <no> <yes|no>
 216         Require and verify server certificate.  If this option is yes,
 217         you must specify ldap_tls_cacert_file or ldap_tls_cacert_dir.
 218
 219 ldap_tls_cacert_file: <none>
 220         File containing CA (Certificate Authority) certificate(s).
 221
 222 ldap_tls_cacert_dir: <none>
 223         Path to directory with CA (Certificate Authority) certificates.
 224
 225 ldap_tls_ciphers: <DEFAULT>
 226         List of SSL/TLS ciphers to allow.  The format of the string is
 227         described in ciphers(1).
 228
 229 ldap_tls_cert: <none>
 230         File containing the client certificate.
 231
 232 ldap_tls_key: <none>
 233         File containing the private client key.
 234
 235 ldap_use_sasl: <no>
 236         Use SASL bind rather than simple bind when connecting to the ldap
 237         server.
 238
 239 ldap_version: <3> <2|3>
 240         Specify the LDAP protocol version.  If ldap_start_tls and/or
 241         ldap_use_sasl are enabled, ldap_version will be automatiacally set to
 242         3.
 243
 244 5. NOTES
 245 --------
 246
 247 For better performance ensure that the attributes specified in ldap_filter are
 248 indexed.
 249
 250 My testing shows that 'custom' is 2-3 times faster than 'bind'
 251 ldap_auth_method.  The 'fastbind' auth_method is just as fast or faster.  The
 252 slower performace of the 'bind' auth_method is caused by two extra calls to
 253 ldap_bind() per each authentication.
 254
 255 SASL bind should be used with the 'fastbind' auth_method:
 256
 257 ldap_servers: ldaps://10.1.1.2/
 258 ldap_use_sasl: yes
 259 ldap_mech: DIGEST_MD5
 260 ldap_auth_method: fastbind
 261
 262 At this time this is not the best performing solution because openldap (2.1.x)
 263 cannot reuse existing connection for multiple ldap_sasl_bind()s.  This will
 264 hopefully change when openldap 2.2 comes out.
 265
 266 6. TODO
 267 -------
 268
 269 - Port to other ldap libraries
 270 - There may be bind problems when following referrals.  Normally this is not an
 271   issue.
 272 - Allow to specify an attribute other than userPassword for use in the custom
 273   authentication method. (Done)
 274 - Add more password hashes such as md5, sha etc (Done)
 275 - Make a suggestion (possibly another authentication method?) (added fastbind)
 276   thanks to Simon Brady <simon.brady@otago.ac.nz>
 277
 278
 279 7. FEEDBACK
 280 -----------
 281
 282 Feedback is much appreciated!  Please drop me a note if you are successfully
 283 using ldap-enabled saslauthd.  Any code improvements and/or suggestion are welcome.
 284
 285 If you have questions, send email to cyrus-sasl@lists.andrew.cmu.edu.  Please
 286 include relevant information about your saslauthd setup: at minimum provide
 287 your saslauth.conf, output from syslog and which directory server you're using.
 288
 289
 290 8. AUTHOR
 291 ---------
 292
 293 Igor Brezac <igor@ipass.net>.