1 package Catalyst::Authentication::Store::LDAP;
6 our $VERSION = '0.1002';
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" },
56 start_tls_options => { verify => "none" },
57 entry_class => "MyApp::LDAP::Entry",
59 user_basedn => "ou=people,dc=yourcompany,dc=com",
61 user_filter => "(&(objectClass=posixAccount)(uid=%s))",
63 user_search_options => { deref => "always" },
64 user_results_filter => sub { return shift->pop_entry },
72 my ( $self, $c ) = @_;
75 id => $c->req->param("login"),
76 password => $c->req->param("password")
78 $c->res->body("Welcome " . $c->user->username . "!");
83 This plugin implements the L<Catalyst::Authentication> v.10 API. Read that documentation first if
84 you are upgrading from a previous version of this plugin.
86 This plugin uses C<Net::LDAP> to let your application authenticate against
87 an LDAP directory. It has a pretty high degree of flexibility, given the
88 wide variation of LDAP directories and schemas from one system to another.
90 It authenticates users in two steps:
92 1) A search of the directory is performed, looking for a user object that
93 matches the username you pass. This is done with the bind credentials
94 supplied in the "binddn" and "bindpw" configuration options.
96 2) If that object is found, we then re-bind to the directory as that object.
97 Assuming this is successful, the user is Authenticated.
99 =head1 CONFIGURATION OPTIONS
101 =head2 Configuring with YAML
103 Set Configuration to be loaded via Config.yml in YourApp.pm
105 use YAML qw(LoadFile);
106 use Path::Class 'file';
110 file(__PACKAGE__->config->{home}, 'Config.yml')
114 Settings in Config.yml (adapt these to whatever configuration format you use):
116 # Config for Store::LDAP
123 password_field: password
124 password_type: self_check
127 ldap_server: ldap.yourcompany.com
135 user_basedn: ou=people,dc=yourcompany,dc=com
136 user_filter: (&(objectClass=posixAccount)(uid=%s))
142 role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
143 role_filter: (&(objectClass=posixGroup)(memberUid=%s))
151 B<NOTE:> The settings above reflect the default values for OpenLDAP. If you
152 are using Active Directory instead, Matija Grabnar suggests that the following
153 tweeks to the example configuration will work:
155 user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
156 user_field: samaccountname
157 user_filter: (sAMAccountName=%s)
159 He also notes: "I found the case in the value of user_field to be significant:
160 it didn't seem to work when I had the mixed case value there."
164 This should be the hostname of your LDAP server.
166 =head2 ldap_server_options
168 This should be a hashref containing options to pass to L<Net::LDAP>->new().
169 See L<Net::LDAP> for the full list.
173 This should be the DN of the object you wish to bind to the directory as
174 during the first phase of authentication. (The user lookup phase)
176 If you supply the value "anonymous" to this option, we will bind anonymously
177 to the directory. This is the default.
181 This is the password for the initial bind.
185 If this is set to 1, we will convert the LDAP connection to use SSL.
187 =head2 start_tls_options
189 This is a hashref, which contains the arguments to the L<Net::LDAP> start_tls
190 method. See L<Net::LDAP> for the complete list of options.
194 This is the basedn for the initial user lookup. Usually points to the
195 top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
199 This is the LDAP Search filter used during user lookup. The special string
200 '%s' will be replaced with the username you pass to $c->login. By default
201 it is set to '(uid=%s)'. Other possibly useful filters:
203 (&(objectClass=posixAccount)(uid=%s))
204 (&(objectClass=User)(cn=%s))
208 This specifies the scope of the search for the initial user lookup. Valid
209 values are "base", "one", and "sub". Defaults to "sub".
213 This is the attribute of the returned LDAP object we will use for their
214 "username". This defaults to "uid". If you had user_filter set to:
216 (&(objectClass=User)(cn=%s))
218 You would probably set this to "cn". You can also set it to an array,
219 to allow more than one login field. The first field will be returned
220 as identifier for the user.
222 =head2 user_search_options
224 This takes a hashref. It will append it's values to the call to
225 L<Net::LDAP>'s "search" method during the initial user lookup. See
226 L<Net::LDAP> for valid options.
228 Be careful not to specify:
234 As they are already taken care of by other configuration options.
236 =head2 user_results_filter
238 This is a Perl CODE ref that can be used to filter out multiple results
239 from your LDAP query. In theory, your LDAP query should only return one result
240 and find_user() will throw an exception if it encounters more than one result.
241 However, if you have, for whatever reason, a legitimate reason for returning
242 multiple search results from your LDAP query, use C<user_results_filter> to filter
243 out the LDAP entries you do not want considered. Your CODE ref should expect
244 a single argument, a Net::LDAP::Search object, and it should return exactly one
245 value, a Net::LDAP::Entry object.
249 user_results_filter => sub {
250 my $search_obj = shift;
251 foreach my $entry ($search_obj->entries) {
252 return $entry if my_match_logic( $entry );
254 return undef; # i.e., no match
259 Whether or not to enable role lookups. It defaults to true; set it to 0 if
260 you want to always avoid role lookups.
264 This should be the basedn where the LDAP Objects representing your roles are.
268 This should be the LDAP Search filter to use during the role lookup. It
269 defaults to '(memberUid=%s)'. The %s in this filter is replaced with the value
270 of the "role_value" configuration option.
272 So, if you had a role_value of "cn", then this would be populated with the cn
273 of the User's LDAP object. The special case is a role_value of "dn", which
274 will be replaced with the User's DN.
278 This specifies the scope of the search for the user's role lookup. Valid
279 values are "base", "one", and "sub". Defaults to "sub".
283 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".
287 This is the attribute of the User object we want to use in our role_filter.
288 If this is set to "dn", we will use the User Objects DN.
290 =head2 role_search_options
292 This takes a hashref. It will append it's values to the call to
293 L<Net::LDAP>'s "search" method during the user's role lookup. See
294 L<Net::LDAP> for valid options.
296 Be careful not to specify:
302 As they are already taken care of by other configuration options.
308 This method will populate
309 L<Catalyst::Plugin::Authentication/default_auth_store> with this object.
313 Adam Jacob <holoway@cpan.org>
315 Some parts stolen shamelessly and entirely from
316 L<Catalyst::Plugin::Authentication::Store::Htpasswd>.
318 Currently maintained by Peter Karman <karman@cpan.org>.
322 To nothingmuch, ghenry, castaway and the rest of #catalyst for the help. :)
326 L<Catalyst::Authentication::Store::LDAP>,
327 L<Catalyst::Authentication::Store::LDAP::User>,
328 L<Catalyst::Authentication::Store::LDAP::Backend>,
329 L<Catalyst::Plugin::Authentication>,
332 =head1 COPYRIGHT & LICENSE
334 Copyright (c) 2005 the aforementioned authors. All rights
335 reserved. This program is free software; you can redistribute
336 it and/or modify it under the same terms as Perl itself.