lib/Catalyst/Authentication/Store/LDAP.pm

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