Mercurial > prosody-modules
annotate mod_lib_ldap/README.md @ 4976:75b6e5df65f9
various: Improve error reporting if missing file server module on 0.12
If there is some error loading net.http.files then it would be swallowed
by the pcall and then it would proceed to trying mod_http_files, which
might cause unexpected behavior on 0.12
Ref #1765
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Mon, 18 Jul 2022 22:47:54 +0200 |
| parents | 71538875be48 |
| children |
| rev | line source |
|---|---|
| 809 | 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 | |
|
1643
71538875be48
mod_lib_ldap: Update README to clarify discussion of auth / TLS... and discourage disabling TLS.
Paul Aurich <paul@darkrain42.org>
parents:
1466
diff
changeset
|
9 **NOTE**: LDAP authentication currently only works with plaintext auth (as opposed to DIGEST-MD5 or SCRAM) |
|
71538875be48
mod_lib_ldap: Update README to clarify discussion of auth / TLS... and discourage disabling TLS.
Paul Aurich <paul@darkrain42.org>
parents:
1466
diff
changeset
|
10 If this isn't ok with you, don't use it! (Or better yet, fix it =) ) |
| 809 | 11 |
|
1643
71538875be48
mod_lib_ldap: Update README to clarify discussion of auth / TLS... and discourage disabling TLS.
Paul Aurich <paul@darkrain42.org>
parents:
1466
diff
changeset
|
12 With that note in mind, if you need to allow (XMPP) clients to connect to your server without TLS and |
|
71538875be48
mod_lib_ldap: Update README to clarify discussion of auth / TLS... and discourage disabling TLS.
Paul Aurich <paul@darkrain42.org>
parents:
1466
diff
changeset
|
13 want to use this module, you need to set 'allow\_unencrypted\_plain\_auth' to true in your |
|
71538875be48
mod_lib_ldap: Update README to clarify discussion of auth / TLS... and discourage disabling TLS.
Paul Aurich <paul@darkrain42.org>
parents:
1466
diff
changeset
|
14 configuration. You probably don't actually want to do this, though. |
| 809 | 15 |
|
862
675945ea2ed6
Change hoelzro's mod_auth_ldap to mod_auth_ldap2
Rob Hoelz <rob@hoelz.ro>
parents:
809
diff
changeset
|
16 To enable LDAP authentication, set 'authentication' to 'ldap2' in your configuration file. |
| 809 | 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 | |
|
1466
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
131 For example, to get something like this in your vCard: |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
132 |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
133 <TEL> |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
134 <WORK /> |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
135 <VOICE /> |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
136 <NUMBER>555-555-5555</NUMBER> |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
137 </TEL> |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
138 |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
139 Your configuration for `telephone` will probably look something like this: |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
140 |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
141 telephone = { |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
142 work = { |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
143 voice = true, |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
144 number = 'telephoneNumber', |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
145 }, |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
146 } |
|
9da03e45c6be
Update LDAP docs for telephone and similar fields
Rob Hoelz <rob@hoelz.ro>
parents:
1224
diff
changeset
|
147 |
| 809 | 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! | |
| 1224 | 170 * Add ability for users to change their vCard/passwords/etc from within Prosody |