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