Mercurial > prosody-modules

comparison mod_lib_ldap/README.md @ 809:1d51c5e38faa

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