1NAME
2 Catalyst::Authentication::Store::LDAP - Authentication from an LDAP
3 Directory.
4
5SYNOPSIS
6 use Catalyst qw(
7 Authentication
8 );
9
10 __PACKAGE__->config(
11 'authentication' => {
12 default_realm => "ldap",
13 realms => {
14 ldap => {
15 credential => {
16 class => "Password",
17 password_field => "password",
18 password_type => "self_check",
19 },
20 store => {
21 binddn => "anonymous",
22 bindpw => "dontcarehow",
23 class => "LDAP",
24 ldap_server => "ldap.yourcompany.com",
25 ldap_server_options => { timeout => 30 },
26 role_basedn => "ou=groups,ou=OxObjects,dc=yourcompany,dc=com",
27 role_field => "uid",
28 role_filter => "(&(objectClass=posixGroup)(memberUid=%s))",
29 role_scope => "one",
30 role_search_options => { deref => "always" },
31 role_value => "dn",
32 role_search_as_user => 0,
33 start_tls => 1,
34 start_tls_options => { verify => "none" },
35 entry_class => "MyApp::LDAP::Entry",
36 use_roles => 1,
37 user_basedn => "ou=people,dc=yourcompany,dc=com",
38 user_field => "uid",
39 user_filter => "(&(objectClass=posixAccount)(uid=%s))",
40 user_scope => "one", # or "sub" for Active Directory
41 user_search_options => {
42 deref => 'always',
43 attrs => [qw( distinguishedname name mail )],
44 },
45 user_results_filter => sub { return shift->pop_entry },
46 persist_in_session => 'all',
47 },
48 },
49 },
50 },
51 );
52
53 sub login : Global {
54 my ( $self, $c ) = @_;
55
56 $c->authenticate({
57 id => $c->req->param("login"),
58 password => $c->req->param("password")
59 });
60 $c->res->body("Welcome " . $c->user->username . "!");
61 }
62
63DESCRIPTION
64 This plugin implements the Catalyst::Authentication v.10 API. Read that
65 documentation first if you are upgrading from a previous version of this
66 plugin.
67
68 This plugin uses "Net::LDAP" to let your application authenticate
69 against an LDAP directory. It has a pretty high degree of flexibility,
70 given the wide variation of LDAP directories and schemas from one system
71 to another.
72
73 It authenticates users in two steps:
74
75 1) A search of the directory is performed, looking for a user object
76 that matches the username you pass. This is done with the bind
77 credentials supplied in the "binddn" and "bindpw" configuration options.
78
79 2) If that object is found, we then re-bind to the directory as that
80 object. Assuming this is successful, the user is Authenticated.
81
82CONFIGURATION OPTIONS
83 Configuring with YAML
84 Set Configuration to be loaded via Config.yml in YourApp.pm
85
86 use YAML qw(LoadFile);
87 use Path::Class 'file';
88
89 __PACKAGE__->config(
90 LoadFile(
91 file(__PACKAGE__->config->{home}, 'Config.yml')
92 )
93 );
94
95 Settings in Config.yml (adapt these to whatever configuration format you
96 use):
97
98 # Config for Store::LDAP
99 authentication:
100 default_realm: ldap
101 realms:
102 ldap:
103 credential:
104 class: Password
105 password_field: password
106 password_type: self_check
107 store:
108 class: LDAP
109 ldap_server: ldap.yourcompany.com
110 ldap_server_options:
111 timeout: 30
112 binddn: anonymous
113 bindpw: dontcarehow
114 start_tls: 1
115 start_tls_options:
116 verify: none
117 user_basedn: ou=people,dc=yourcompany,dc=com
118 user_filter: (&(objectClass=posixAccount)(uid=%s))
119 user_scope: one
120 user_field: uid
121 user_search_options:
122 deref: always
123 use_roles: 1
124 role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
125 role_filter: (&(objectClass=posixGroup)(memberUid=%s))
126 role_scope: one
127 role_field: uid
128 role_value: dn
129 role_search_options:
130 deref: always
131
132 NOTE: The settings above reflect the default values for OpenLDAP. If you
133 are using Active Directory instead, Matija Grabnar suggests that the
134 following tweeks to the example configuration will work:
135
136 user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
137 user_field: samaccountname
138 user_filter: (sAMAccountName=%s)
139 user_scope: sub
140
141 He also notes: "I found the case in the value of user_field to be
142 significant: it didn't seem to work when I had the mixed case value
143 there."
144
145 ldap_server
146 This should be the hostname of your LDAP server.
147
148 ldap_server_options
149 This should be a hashref containing options to pass to Net::LDAP->new().
150 See Net::LDAP for the full list.
151
152 binddn
153 This should be the DN of the object you wish to bind to the directory as
154 during the first phase of authentication. (The user lookup phase)
155
156 If you supply the value "anonymous" to this option, we will bind
157 anonymously to the directory. This is the default.
158
159 bindpw
160 This is the password for the initial bind.
161
162 start_tls
163 If this is set to 1, we will convert the LDAP connection to use SSL.
164
165 start_tls_options
166 This is a hashref, which contains the arguments to the Net::LDAP
167 start_tls method. See Net::LDAP for the complete list of options.
168
169 user_basedn
170 This is the basedn for the initial user lookup. Usually points to the
171 top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
172
173 user_filter
174 This is the LDAP Search filter used during user lookup. The special
175 string '%s' will be replaced with the username you pass to $c->login. By
176 default it is set to '(uid=%s)'. Other possibly useful filters:
177
178 (&(objectClass=posixAccount)(uid=%s))
179 (&(objectClass=User)(cn=%s))
180
181 user_scope
182 This specifies the scope of the search for the initial user lookup.
183 Valid values are "base", "one", and "sub". Defaults to "sub".
184
185 user_field
186 This is the attribute of the returned LDAP object we will use for their
187 "username". This defaults to "uid". If you had user_filter set to:
188
189 (&(objectClass=User)(cn=%s))
190
191 You would probably set this to "cn". You can also set it to an array, to
192 allow more than one login field. The first field will be returned as
193 identifier for the user.
194
195 user_search_options
196 This takes a hashref. It will append its values to the call to
197 Net::LDAP's "search" method during the initial user lookup. See
198 Net::LDAP for valid options.
199
200 Be careful not to specify:
201
202 filter
203 scope
204 base
205
206 As they are already taken care of by other configuration options.
207
208 user_results_filter
209 This is a Perl CODE ref that can be used to filter out multiple results
210 from your LDAP query. In theory, your LDAP query should only return one
211 result and find_user() will throw an exception if it encounters more
212 than one result. However, if you have, for whatever reason, a legitimate
213 reason for returning multiple search results from your LDAP query, use
214 "user_results_filter" to filter out the LDAP entries you do not want
215 considered. Your CODE ref should expect a single argument, a
216 Net::LDAP::Search object, and it should return exactly one value, a
217 Net::LDAP::Entry object.
218
219 Example:
220
221 user_results_filter => sub {
222 my $search_obj = shift;
223 foreach my $entry ($search_obj->entries) {
224 return $entry if my_match_logic( $entry );
225 }
226 return undef; # i.e., no match
227 }
228
229 use_roles
230 Whether or not to enable role lookups. It defaults to true; set it to 0
231 if you want to always avoid role lookups.
232
233 role_basedn
234 This should be the basedn where the LDAP Objects representing your roles
235 are.
236
237 role_filter
238 This should be the LDAP Search filter to use during the role lookup. It
239 defaults to '(memberUid=%s)'. The %s in this filter is replaced with the
240 value of the "role_value" configuration option.
241
242 So, if you had a role_value of "cn", then this would be populated with
243 the cn of the User's LDAP object. The special case is a role_value of
244 "dn", which will be replaced with the User's DN.
245
246 role_scope
247 This specifies the scope of the search for the user's role lookup. Valid
248 values are "base", "one", and "sub". Defaults to "sub".
249
250 role_field
251 Should be set to the Attribute of the Role Object's returned during Role
252 lookup you want to use as the "name" of the role. Defaults to "CN".
253
254 role_value
255 This is the attribute of the User object we want to use in our
256 role_filter. If this is set to "dn", we will use the User Objects DN.
257
258 role_search_options
259 This takes a hashref. It will append its values to the call to
260 Net::LDAP's "search" method during the user's role lookup. See Net::LDAP
261 for valid options.
262
263 Be careful not to specify:
264
265 filter
266 scope
267 base
268
269 As they are already taken care of by other configuration options.
270
271 role_search_as_user
272 By default this setting is false, and the role search will be performed
273 by binding to the directory with the details in the *binddn* and
274 *bindpw* fields. If this is set to false, then the role search will
275 instead be performed when bound as the user you authenticated as.
276
277 persist_in_session
278 Can take one of the following values, defaults to "username":
279
280 "username"
281 Only store the username in the session and lookup the user and its
282 roles on every request. That was how the module worked until version
283 1.015 and is also the default for backwards compatibility.
284
285 "all"
286 Store the user object and its roles in the session and never look it
287 up in the store after login.
288
289 NOTE: It's recommended to limit the user attributes fetched from
290 LDAP using "user_search_options" / "attrs" to not exhaust the
291 session store.
292
293 entry_class
294 The name of the class of LDAP entries returned. This class should exist
295 and is expected to be a subclass of Net::LDAP::Entry
296
297 user_class
298 The name of the class of user object returned. By default, this is
299 Catalyst::Authentication::Store::LDAP::User.
300
301METHODS
302 new
303 This method will populate "default_auth_store" in
304 Catalyst::Plugin::Authentication with this object.
305
306AUTHORS
307 Adam Jacob <holoway@cpan.org> Peter Karman <karman@cpan.org> Alexander
308 Hartmaier <abraxxa@cpan.org>
309
310 Some parts stolen shamelessly and entirely from
311 Catalyst::Plugin::Authentication::Store::Htpasswd.
312
313 Currently maintained by Dagfinn Ilmari Mannsåker <ilmari@cpan.org>.
314
315THANKS
316 To nothingmuch, ghenry, castaway and the rest of #catalyst for the help.
317 :)
318
319SEE ALSO
320 Catalyst::Authentication::Store::LDAP,
321 Catalyst::Authentication::Store::LDAP::User,
322 Catalyst::Authentication::Store::LDAP::Backend,
323 Catalyst::Plugin::Authentication, Net::LDAP
324
325COPYRIGHT & LICENSE
326 Copyright (c) 2005 the aforementioned authors. All rights reserved. This
327 program is free software; you can redistribute it and/or modify it under
328 the same terms as Perl itself.
329
330