git.sur5r.net Git - openldap/blob - contrib/ldapsasl/README

   1 LDAP auxprop plugin for SASL-enabled servers.
   2 Copyright (C) 2002,2003 by Howard Chu, hyc@symas.com
   3
   4 This software is licensed under the terms of the OpenLDAP license.
   5
   6 The file ldapdb.c was written for Cyrus SASL 2.1.3 and OpenLDAP 2.1.3.
   7 Due to various bugs in the Cyrus source you should use Cyrus SASL 2.1.15
   8 or newer. You need at least Cyrus SASL 2.1.16 to use the auxprop-store
   9 functionality.
  10
  11 The version of ldapdb bundled with OpenLDAP 2.1.22 and older will work
  12 with all OpenLDAP releases 2.1.3 and up. The ldapdb in OpenLDAP 2.1.23
  13 uses a different LDAP request and requires the server to be 2.1.23 or newer.
  14
  15 It can be compiled by copying into the Cyrus SASL source tree, in the
  16 plugins subdirectory. No configuration or build script is provided.
  17
  18 To compile, type "make ldapdb.lo". To link, you'll have to copy the
  19 link rule for one of the other plugins. Below is a sample on my Linux
  20 system:
  21
  22         /bin/sh ../libtool --mode=link gcc  -Wall -W -g -O2 -L/usr/local/lib -Wl,-rpath,/usr/local/lib -module -export-dynamic -rpath /usr/lib/sasl2 -o libldapdb.la  -version-info 2:4:0 ldapdb.lo -lldap -llber -lssl -lcrypto
  23
  24 Once installed, you need to add some config items to the SASL server's
  25 config file in /usr/lib/sasl2. For example:
  26
  27 ldapdb_uri: ldap://ldap.example.com
  28 ldapdb_id: root
  29 ldapdb_pw: secret
  30 ldapdb_mech: DIGEST-MD5
  31
  32 This config assumes an LDAP server on the same machine as the server
  33 that is using SASL. The LDAP server must be configured to map the SASL
  34 authcId "root" into a DN that has proxy authorization privileges to
  35 every account that is allowed to login to this server. (See the OpenLDAP
  36 Admin Guide section 10 for details.)
  37
  38 Unlike other LDAP-enabled plugins for other services that are common
  39 on the web, this plugin does not require you to configure DN search
  40 patterns to map usernames to LDAP DNs. This plugin requires SASL name
  41 mapping to be configured on the target slapd. This approach keeps the
  42 LDAP-specific configuration details in one place, the slapd.conf, and
  43 makes the configuration of remote services much simpler.
  44
  45 An additional keyword "ldapdb_rc" may be specified in the config file.
  46 The filename specified here will be put into the server's LDAPRC
  47 environment variable, and libldap-specific config options may be set
  48 in that ldaprc file. The main purpose behind this option is to allow
  49 a client TLS certificate to be configured, so that SASL/EXTERNAL may
  50 be used between the SASL server and the LDAP server. This is the most
  51 optimal way to use this plugin when the servers are on separate machines.
  52
  53 Note: this plugin is not for use with slapd itself. When OpenLDAP is
  54 built with SASL support, slapd uses its own internal auxprop module.
  55 By default, without configuring anything else, slapd will fail to load
  56 the ldapdb module when it's present. This is as it should be. If you
  57 don't like the "auxpropfunc: error -7" message that is sent to syslog
  58 by slapd, you can stop it by creating /usr/lib/sasl2/slapd.conf with:
  59
  60         auxprop_plugin: slapd
  61
  62 which will force the SASL library to ignore all other auxprop modules.
  63
  64 This plugin has been in use for over a year at many sites with good
  65 results. If you have questions or problems, please send feedback via
  66 the openldap-software mailing list.
  67
  68   -- Howard Chu
  69
  70 Update... With OpenLDAP 2.1.13 you can use SASL/EXTERNAL on ldapi://.
  71 This is fast and secure, and needs no username or password to be stored.
  72 The SASL config file is just
  73
  74 ldapdb_uri: ldapi://
  75 ldapdb_mech: EXTERNAL
  76
  77 The slapd.conf will need to map these usernames to LDAP DNs:
  78
  79 sasl-regexp uidNumber=(.*)\\+gidNumber=(.*),cn=peercred,cn=external,cn=auth
  80         ldap:///dc=example,dc=com??sub?(&(uidNumber=$1)(gidNumber=$2))
  81
  82 sasl-regexp uid=(.*),cn=external,cn=auth
  83         ldap:///dc=example,dc=com??sub?(uid=$1)
  84
  85 Update... With OpenLDAP 2.1.23 you can use the ldapdb_starttls keyword
  86 to use the StartTLS extended operation on an LDAP session. This item
  87 may be set to either "try" or "demand", e.g.:
  88
  89 ldapdb_uri: ldap://ldap.example.com
  90 ldapdb_starttls: try
  91
  92 When set to "try" any failure in StartTLS is ignored. When set to "demand"
  93 then any failure aborts the connection.