1 package Catalyst::Authentication::Store::LDAP;
6 our $VERSION = '1.015';
8 use Catalyst::Authentication::Store::LDAP::Backend;
11 my ( $class, $config, $app ) = @_;
12 return Catalyst::Authentication::Store::LDAP::Backend->new(
24 Catalyst::Authentication::Store::LDAP
25 - Authentication from an LDAP Directory.
35 default_realm => "ldap",
40 password_field => "password",
41 password_type => "self_check",
44 binddn => "anonymous",
45 bindpw => "dontcarehow",
47 ldap_server => "ldap.yourcompany.com",
48 ldap_server_options => { timeout => 30 },
49 role_basedn => "ou=groups,ou=OxObjects,dc=yourcompany,dc=com",
51 role_filter => "(&(objectClass=posixGroup)(memberUid=%s))",
53 role_search_options => { deref => "always" },
55 role_search_as_user => 0,
57 start_tls_options => { verify => "none" },
58 entry_class => "MyApp::LDAP::Entry",
60 user_basedn => "ou=people,dc=yourcompany,dc=com",
62 user_filter => "(&(objectClass=posixAccount)(uid=%s))",
63 user_scope => "one", # or "sub" for Active Directory
64 user_search_options => {
66 attrs => [qw( distinguishedname name mail )],
68 user_results_filter => sub { return shift->pop_entry },
69 persist_in_session => 'all',
77 my ( $self, $c ) = @_;
80 id => $c->req->param("login"),
81 password => $c->req->param("password")
83 $c->res->body("Welcome " . $c->user->username . "!");
88 This plugin implements the L<Catalyst::Authentication> v.10 API. Read that documentation first if
89 you are upgrading from a previous version of this plugin.
91 This plugin uses C<Net::LDAP> to let your application authenticate against
92 an LDAP directory. It has a pretty high degree of flexibility, given the
93 wide variation of LDAP directories and schemas from one system to another.
95 It authenticates users in two steps:
97 1) A search of the directory is performed, looking for a user object that
98 matches the username you pass. This is done with the bind credentials
99 supplied in the "binddn" and "bindpw" configuration options.
101 2) If that object is found, we then re-bind to the directory as that object.
102 Assuming this is successful, the user is Authenticated.
104 =head1 CONFIGURATION OPTIONS
106 =head2 Configuring with YAML
108 Set Configuration to be loaded via Config.yml in YourApp.pm
110 use YAML qw(LoadFile);
111 use Path::Class 'file';
115 file(__PACKAGE__->config->{home}, 'Config.yml')
119 Settings in Config.yml (adapt these to whatever configuration format you use):
121 # Config for Store::LDAP
128 password_field: password
129 password_type: self_check
132 ldap_server: ldap.yourcompany.com
140 user_basedn: ou=people,dc=yourcompany,dc=com
141 user_filter: (&(objectClass=posixAccount)(uid=%s))
147 role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
148 role_filter: (&(objectClass=posixGroup)(memberUid=%s))
156 B<NOTE:> The settings above reflect the default values for OpenLDAP. If you
157 are using Active Directory instead, Matija Grabnar suggests that the following
158 tweeks to the example configuration will work:
160 user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
161 user_field: samaccountname
162 user_filter: (sAMAccountName=%s)
165 He also notes: "I found the case in the value of user_field to be significant:
166 it didn't seem to work when I had the mixed case value there."
170 This should be the hostname of your LDAP server.
172 =head2 ldap_server_options
174 This should be a hashref containing options to pass to L<Net::LDAP>->new().
175 See L<Net::LDAP> for the full list.
179 This should be the DN of the object you wish to bind to the directory as
180 during the first phase of authentication. (The user lookup phase)
182 If you supply the value "anonymous" to this option, we will bind anonymously
183 to the directory. This is the default.
187 This is the password for the initial bind.
191 If this is set to 1, we will convert the LDAP connection to use SSL.
193 =head2 start_tls_options
195 This is a hashref, which contains the arguments to the L<Net::LDAP> start_tls
196 method. See L<Net::LDAP> for the complete list of options.
200 This is the basedn for the initial user lookup. Usually points to the
201 top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
205 This is the LDAP Search filter used during user lookup. The special string
206 '%s' will be replaced with the username you pass to $c->login. By default
207 it is set to '(uid=%s)'. Other possibly useful filters:
209 (&(objectClass=posixAccount)(uid=%s))
210 (&(objectClass=User)(cn=%s))
214 This specifies the scope of the search for the initial user lookup. Valid
215 values are "base", "one", and "sub". Defaults to "sub".
219 This is the attribute of the returned LDAP object we will use for their
220 "username". This defaults to "uid". If you had user_filter set to:
222 (&(objectClass=User)(cn=%s))
224 You would probably set this to "cn". You can also set it to an array,
225 to allow more than one login field. The first field will be returned
226 as identifier for the user.
228 =head2 user_search_options
230 This takes a hashref. It will append it's values to the call to
231 L<Net::LDAP>'s "search" method during the initial user lookup. See
232 L<Net::LDAP> for valid options.
234 Be careful not to specify:
240 As they are already taken care of by other configuration options.
242 =head2 user_results_filter
244 This is a Perl CODE ref that can be used to filter out multiple results
245 from your LDAP query. In theory, your LDAP query should only return one result
246 and find_user() will throw an exception if it encounters more than one result.
247 However, if you have, for whatever reason, a legitimate reason for returning
248 multiple search results from your LDAP query, use C<user_results_filter> to filter
249 out the LDAP entries you do not want considered. Your CODE ref should expect
250 a single argument, a Net::LDAP::Search object, and it should return exactly one
251 value, a Net::LDAP::Entry object.
255 user_results_filter => sub {
256 my $search_obj = shift;
257 foreach my $entry ($search_obj->entries) {
258 return $entry if my_match_logic( $entry );
260 return undef; # i.e., no match
265 Whether or not to enable role lookups. It defaults to true; set it to 0 if
266 you want to always avoid role lookups.
270 This should be the basedn where the LDAP Objects representing your roles are.
274 This should be the LDAP Search filter to use during the role lookup. It
275 defaults to '(memberUid=%s)'. The %s in this filter is replaced with the value
276 of the "role_value" configuration option.
278 So, if you had a role_value of "cn", then this would be populated with the cn
279 of the User's LDAP object. The special case is a role_value of "dn", which
280 will be replaced with the User's DN.
284 This specifies the scope of the search for the user's role lookup. Valid
285 values are "base", "one", and "sub". Defaults to "sub".
289 Should be set to the Attribute of the Role Object's returned during Role lookup you want to use as the "name" of the role. Defaults to "CN".
293 This is the attribute of the User object we want to use in our role_filter.
294 If this is set to "dn", we will use the User Objects DN.
296 =head2 role_search_options
298 This takes a hashref. It will append it's values to the call to
299 L<Net::LDAP>'s "search" method during the user's role lookup. See
300 L<Net::LDAP> for valid options.
302 Be careful not to specify:
308 As they are already taken care of by other configuration options.
310 =head2 role_search_as_user
312 By default this setting is false, and the role search will be performed
313 by binding to the directory with the details in the I<binddn> and I<bindpw>
314 fields. If this is set to false, then the role search will instead be
315 performed when bound as the user you authenticated as.
317 =head2 persist_in_session
319 Can take one of the following values, defaults to undefined:
323 Only store the username in the session and lookup the user and its roles
324 on every request. That was how the module worked until version 1.015 and is
325 also the default for backwards compatibility.
329 Store the user object and its roles in the session and never look it up in
330 the store after login.
332 B<NOTE:> It's recommended to limit the user attributes fetched from LDAP
333 using L<user_search_options> / attrs to not exhaust the session store..
337 The name of the class of LDAP entries returned. This class should
338 exist and is expected to be a subclass of Net::LDAP::Entry
342 The name of the class of user object returned. By default, this is
343 L<Catalyst::Authentication::Store::LDAP::User>.
349 This method will populate
350 L<Catalyst::Plugin::Authentication/default_auth_store> with this object.
354 Adam Jacob <holoway@cpan.org>
356 Some parts stolen shamelessly and entirely from
357 L<Catalyst::Plugin::Authentication::Store::Htpasswd>.
359 Currently maintained by Peter Karman <karman@cpan.org>.
363 To nothingmuch, ghenry, castaway and the rest of #catalyst for the help. :)
367 L<Catalyst::Authentication::Store::LDAP>,
368 L<Catalyst::Authentication::Store::LDAP::User>,
369 L<Catalyst::Authentication::Store::LDAP::Backend>,
370 L<Catalyst::Plugin::Authentication>,
373 =head1 COPYRIGHT & LICENSE
375 Copyright (c) 2005 the aforementioned authors. All rights
376 reserved. This program is free software; you can redistribute
377 it and/or modify it under the same terms as Perl itself.