1 package Catalyst::Authentication::Store::LDAP;
6 our $VERSION = '0.1000';
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.
31 Authentication::Store::LDAP
32 Authentication::Credential::Password
37 default_realm => "ldap",
42 password_field => "password",
43 password_type => "self_check",
46 binddn => "anonymous",
47 bindpw => "dontcarehow",
49 ldap_server => "ldap.yourcompany.com",
50 ldap_server_options => { timeout => 30 },
51 role_basedn => "ou=groups,ou=OxObjects,dc=yourcompany,dc=com",
53 role_filter => "(&(objectClass=posixGroup)(memberUid=%s))",
55 role_search_options => { deref => "always" },
58 start_tls_options => { verify => "none" },
59 entry_class => "MyApp::LDAP::Entry",
61 user_basedn => "ou=people,dc=yourcompany,dc=com",
63 user_filter => "(&(objectClass=posixAccount)(uid=%s))",
65 user_search_options => { deref => "always" },
73 my ( $self, $c ) = @_;
76 id => $c->req->param("login"),
77 password => $c->req->param("password")
79 $c->res->body("Welcome " . $c->user->username . "!");
84 This plugin implements the L<Catalyst::Authentication> v.10 API. Read that documentation first if
85 you are upgrading from a previous version of this plugin.
87 This plugin uses C<Net::LDAP> to let your application authenticate against
88 an LDAP directory. It has a pretty high degree of flexibility, given the
89 wide variation of LDAP directories and schemas from one system to another.
91 It authenticates users in two steps:
93 1) A search of the directory is performed, looking for a user object that
94 matches the username you pass. This is done with the bind credentials
95 supplied in the "binddn" and "bindpw" configuration options.
97 2) If that object is found, we then re-bind to the directory as that object.
98 Assuming this is successful, the user is Authenticated.
100 =head1 CONFIGURATION OPTIONS
102 =head2 Configuring with YAML
104 Set Configuration to be loaded via Config.yml in YourApp.pm
106 use YAML qw(LoadFile);
107 use Path::Class 'file';
111 file(__PACKAGE__->config->{home}, 'Config.yml')
115 Settings in Config.yml (adapt these to whatever configuration format you use):
117 # Config for Store::LDAP
124 password_field: password
125 password_type: self_check
128 ldap_server: ldap.yourcompany.com
136 user_basedn: ou=people,dc=yourcompany,dc=com
137 user_filter: (&(objectClass=posixAccount)(uid=%s))
143 role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
144 role_filter: (&(objectClass=posixGroup)(memberUid=%s))
152 B<NOTE:> The settings above reflect the default values for OpenLDAP. If you
153 are using Active Directory instead, Matija Grabnar suggests that the following
154 tweeks to the example configuration will work:
156 user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
157 user_field: samaccountname
158 user_filter: (sAMAccountName=%s)
160 He also notes: "I found the case in the value of user_field to be significant:
161 it didn't seem to work when I had the mixed case value there."
165 This should be the hostname of your LDAP server.
167 =head2 ldap_server_options
169 This should be a hashref containing options to pass to L<Net::LDAP>->new().
170 See L<Net::LDAP> for the full list.
174 This should be the DN of the object you wish to bind to the directory as
175 during the first phase of authentication. (The user lookup phase)
177 If you supply the value "anonymous" to this option, we will bind anonymously
178 to the directory. This is the default.
182 This is the password for the initial bind.
186 If this is set to 1, we will convert the LDAP connection to use SSL.
188 =head2 start_tls_options
190 This is a hashref, which contains the arguments to the L<Net::LDAP> start_tls
191 method. See L<Net::LDAP> for the complete list of options.
195 This is the basedn for the initial user lookup. Usually points to the
196 top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
200 This is the LDAP Search filter used during user lookup. The special string
201 '%s' will be replaced with the username you pass to $c->login. By default
202 it is set to '(uid=%s)'. Other possibly useful filters:
204 (&(objectClass=posixAccount)(uid=%s))
205 (&(objectClass=User)(cn=%s))
209 This specifies the scope of the search for the initial user lookup. Valid
210 values are "base", "one", and "sub". Defaults to "sub".
214 This is the attribute of the returned LDAP object we will use for their
215 "username". This defaults to "uid". If you had user_filter set to:
217 (&(objectClass=User)(cn=%s))
219 You would probably set this to "cn". You can also set it to an array,
220 to allow more than one login field. The first field will be returned
221 as identifier for the user.
223 =head2 user_search_options
225 This takes a hashref. It will append it's values to the call to
226 L<Net::LDAP>'s "search" method during the initial user lookup. See
227 L<Net::LDAP> for valid options.
229 Be careful not to specify:
235 As they are already taken care of by other configuration options.
239 Whether or not to enable role lookups. It defaults to true; set it to 0 if
240 you want to always avoid role lookups.
244 This should be the basedn where the LDAP Objects representing your roles are.
248 This should be the LDAP Search filter to use during the role lookup. It
249 defaults to '(memberUid=%s)'. The %s in this filter is replaced with the value
250 of the "role_value" configuration option.
252 So, if you had a role_value of "cn", then this would be populated with the cn
253 of the User's LDAP object. The special case is a role_value of "dn", which
254 will be replaced with the User's DN.
258 This specifies the scope of the search for the user's role lookup. Valid
259 values are "base", "one", and "sub". Defaults to "sub".
263 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".
267 This is the attribute of the User object we want to use in our role_filter.
268 If this is set to "dn", we will use the User Objects DN.
270 =head2 role_search_options
272 This takes a hashref. It will append it's values to the call to
273 L<Net::LDAP>'s "search" method during the user's role lookup. See
274 L<Net::LDAP> for valid options.
276 Be careful not to specify:
282 As they are already taken care of by other configuration options.
288 This method will populate
289 L<Catalyst::Plugin::Authentication/default_auth_store> with this object.
293 Adam Jacob <holoway@cpan.org>
295 Some parts stolen shamelessly and entirely from
296 L<Catalyst::Plugin::Authentication::Store::Htpasswd>.
298 Currently maintained by Peter Karman <karman@cpan.org>.
302 To nothingmuch, ghenry, castaway and the rest of #catalyst for the help. :)
306 L<Catalyst::Authentication::Store::LDAP>,
307 L<Catalyst::Authentication::Store::LDAP::User>,
308 L<Catalyst::Authentication::Store::LDAP::Backend>,
309 L<Catalyst::Plugin::Authentication>,
312 =head1 COPYRIGHT & LICENSE
314 Copyright (c) 2005 the aforementioned authors. All rights
315 reserved. This program is free software; you can redistribute
316 it and/or modify it under the same terms as Perl itself.