mod_lib_ldap/README.md

   1 # LDAP plugin suite for Prosody
   2
   3 The LDAP plugin suite includes an authentication plugin (mod\_auth\_ldap2) and storage plugin
   4 (mod\_storage\_ldap) to query against an LDAP server.  It also provides a plugin library (mod\_lib\_ldap)
   5 for accessing an LDAP server to make writing other LDAP-based plugins easier in the future.
   6
   7 # LDAP Authentication
   8
   9 **NOTE**: LDAP authentication currently only works with plaintext auth (as opposed to DIGEST-MD5 or SCRAM)
  10 If this isn't ok with you, don't use it!  (Or better yet, fix it =) )
  11
  12 With that note in mind, if you need to allow (XMPP) clients to connect to your server without TLS and
  13 want to use this module, you need to set 'allow\_unencrypted\_plain\_auth' to true in your
  14 configuration.  You probably don't actually want to do this, though.
  15
  16 To enable LDAP authentication, set 'authentication' to 'ldap2' in your configuration file.
  17 See also http://prosody.im/doc/authentication.
  18
  19 # LDAP Storage
  20
  21 LDAP storage is currently read-only, and it only supports rosters and vCards.
  22
  23 To enable LDAP storage, set 'storage' to 'ldap' in your configuration file.
  24 See also http://prosody.im/doc/storage.
  25
  26 # LDAP Configuration
  27
  28 All of the LDAP-specific configuration for the plugin set goes into an 'ldap' section
  29 in the configuration.  You must set the 'hostname' field in the 'ldap' section to
  30 your LDAP server's location (a custom port is also accepted, so I guess it's not strictly
  31 a hostname).  The 'bind\_dn' and 'bind\_password' are optional if you want to bind as
  32 a specific DN.  There should be an example configuration included with this README, so
  33 feel free to consult that.
  34
  35 ## The user section
  36
  37 The user section must contain the following keys:
  38
  39   * basedn - The base DN against which to base your LDAP queries for users.
  40   * filter - An LDAP filter expression that matches users.
  41   * usernamefield - The name of the attribute in an LDAP entry that contains the username.
  42   * namefield - The name of the attribute in an LDAP entry that contains the user's real name.
  43
  44 ## The groups section
  45
  46 The LDAP plugin suite has support for grouping (ala mod\_groups), which can be enabled via the groups
  47 section in the ldap section of the configuration file.  Currently, you must have at least one group.
  48 The groups section must contain the following keys:
  49
  50   * basedn - The base DN against which to base your LDAP queries for groups.
  51   * memberfield - The name of the attribute in an LDAP entry that contains a list of a group's members. The contents of this field
  52                   must match usernamefield in the user section.
  53   * namefield - The name of the attribute in an LDAP entry that contains the group's name.
  54
  55 The groups section must contain at least one entry in its array section.  Each entry must be a table, with the following keys:
  56
  57   * name - The name of the group that will be presented in the roster.
  58   * $namefield (whatever namefield is set to is the name) - An attribute pair to match this group against.
  59   * admin (optional) - whether or not this group's members are admins.
  60
  61 ## The vcard\_format section
  62
  63 The vcard\_format section is used to generate a vCard given an LDAP entry.  See http://xmpp.org/extensions/xep-0054.html for
  64 more information.  The JABBERID field is automatically populated.
  65
  66 The key/value pairs in this table fall into three categories:
  67
  68 ### Simple pairs
  69
  70 Some values in the vcard\_format table are simple key-value pairs, where the key corresponds to a vCard
  71 entry, and the value corresponds to the attribute name in the LDAP entry for the user.  The fields that
  72 be configured this way are:
  73
  74   * displayname - corresponds to FN
  75   * nickname - corresponds to NICKNAME
  76   * birthday - corresponds to BDAY
  77   * mailer - corresponds to MAILER
  78   * timezone - corresponds to TZ
  79   * title - corresponds to TITLE
  80   * role - corresponds to ROLE
  81   * note - corresponds to NOTE
  82   * rev - corresponds to REV
  83   * sortstring - corresponds to SORT-STRING
  84   * uid - corresponds to UID
  85   * url - corresponds to URL
  86   * description - corresponds to DESC
  87
  88 ### Single-level fields
  89
  90 These pairs have a table as their values, and the table itself has a series of key value pairs that are translated
  91 similarly to simple pairs.  The fields that are configured this way are:
  92
  93   * name - corresponds to N
  94     * family - corresponds to FAMILY
  95     * given - corresponds toGIVEN
  96     * middle - corresponds toMIDDLE
  97     * prefix - corresponds toPREFIX
  98     * suffix - corresponds toSUFFIX
  99   * photo - corresponds to PHOTO
 100     * type - corresponds to TYPE
 101     * binval - corresponds to BINVAL
 102     * extval - corresponds to EXTVAL
 103   * geo - corresponds to GEO
 104     * lat - corresponds to LAT
 105     * lon - corresponds to LON
 106   * logo - corresponds to LOGO
 107     * type - corresponds to TYPE
 108     * binval - corresponds to BINVAL
 109     * extval - corresponds to EXTVAL
 110   * org - corresponds to ORG
 111     * orgname - corresponds to ORGNAME
 112     * orgunit - corresponds to ORGUNIT
 113   * sound - corresponds to SOUND
 114     * phonetic - corresponds to PHONETIC
 115     * binval - corresponds to BINVAL
 116     * extval - corresponds to EXTVAL
 117   * key - corresponds to KEY
 118     * type - corresponds to TYPE
 119     * cred - corresponds to CRED
 120
 121 ### Multi-level fields
 122
 123 These pairs have a table as their values, and each table itself has tables as its values.  The nested tables have
 124 the same key-value pairs you're used to, the only difference being that values may have a boolean as their type, which
 125 converts them into an empty XML tag.  I recommend looking at the example configuration for clarification.
 126
 127   * address - ADR
 128   * telephone - TEL
 129   * email - EMAIL
 130
 131 For example, to get something like this in your vCard:
 132
 133     <TEL>
 134       <WORK />
 135       <VOICE />
 136       <NUMBER>555-555-5555</NUMBER>
 137     </TEL>
 138
 139 Your configuration for `telephone` will probably look something like this:
 140
 141     telephone = {
 142       work = {
 143         voice = true,
 144         number = 'telephoneNumber',
 145       },
 146     }
 147
 148 ### Unsupported vCard fields
 149
 150   * LABEL
 151   * AGENT
 152   * CATEGORIES
 153   * PRODID
 154   * CLASS
 155
 156 ### Example Configuration
 157
 158 You can find an example configuration in the dev directory underneath the
 159 directory that this file is located in.
 160
 161 # Missing Features
 162
 163 This set of plugins is missing a few features, some of which are really just ideas:
 164
 165   * Implement non-plaintext authentication.
 166   * Use proper LDAP binding (LuaLDAP must be patched with http://prosody.im/patches/lualdap.patch, though)
 167   * Non-hardcoded LDAP groups (derive groups from LDAP queries)
 168   * LDAP-based MUCs (like a private MUC per group, or something)
 169   * This suite of plugins was developed with a POSIX-style setup in mind; YMMV. Patches to work with other setups are welcome!
 170   * Add ability for users to change their vCard/passwords/etc from within Prosody