README

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