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",
  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
 136     He also notes: "I found the case in the value of user_field to be
 137     significant: it didn't seem to work when I had the mixed case value
 138     there."
 139
 140   ldap_server
 141     This should be the hostname of your LDAP server.
 142
 143   ldap_server_options
 144     This should be a hashref containing options to pass to Net::LDAP->new().
 145     See Net::LDAP for the full list.
 146
 147   binddn
 148     This should be the DN of the object you wish to bind to the directory as
 149     during the first phase of authentication. (The user lookup phase)
 150
 151     If you supply the value "anonymous" to this option, we will bind
 152     anonymously to the directory. This is the default.
 153
 154   bindpw
 155     This is the password for the initial bind.
 156
 157   start_tls
 158     If this is set to 1, we will convert the LDAP connection to use SSL.
 159
 160   start_tls_options
 161     This is a hashref, which contains the arguments to the Net::LDAP
 162     start_tls method. See Net::LDAP for the complete list of options.
 163
 164   user_basedn
 165     This is the basedn for the initial user lookup. Usually points to the
 166     top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
 167
 168   user_filter
 169     This is the LDAP Search filter used during user lookup. The special
 170     string '%s' will be replaced with the username you pass to $c->login. By
 171     default it is set to '(uid=%s)'. Other possibly useful filters:
 172
 173         (&(objectClass=posixAccount)(uid=%s))
 174         (&(objectClass=User)(cn=%s))
 175
 176   user_scope
 177     This specifies the scope of the search for the initial user lookup.
 178     Valid values are "base", "one", and "sub". Defaults to "sub".
 179
 180   user_field
 181     This is the attribute of the returned LDAP object we will use for their
 182     "username". This defaults to "uid". If you had user_filter set to:
 183
 184         (&(objectClass=User)(cn=%s))
 185
 186     You would probably set this to "cn". You can also set it to an array, to
 187     allow more than one login field. The first field will be returned as
 188     identifier for the user.
 189
 190   user_search_options
 191     This takes a hashref. It will append it's values to the call to
 192     Net::LDAP's "search" method during the initial user lookup. See
 193     Net::LDAP for valid options.
 194
 195     Be careful not to specify:
 196
 197         filter
 198         scope
 199         base
 200
 201     As they are already taken care of by other configuration options.
 202
 203   user_results_filter
 204     This is a Perl CODE ref that can be used to filter out multiple results
 205     from your LDAP query. In theory, your LDAP query should only return one
 206     result and find_user() will throw an exception if it encounters more
 207     than one result. However, if you have, for whatever reason, a legitimate
 208     reason for returning multiple search results from your LDAP query, use
 209     "user_results_filter" to filter out the LDAP entries you do not want
 210     considered. Your CODE ref should expect a single argument, a
 211     Net::LDAP::Search object, and it should return exactly one value, a
 212     Net::LDAP::Entry object.
 213
 214     Example:
 215
 216      user_results_filter => sub {
 217                               my $search_obj = shift;
 218                               foreach my $entry ($search_obj->entries) {
 219                                   return $entry if my_match_logic( $entry );
 220                               }
 221                               return undef; # i.e., no match
 222                             }
 223
 224   use_roles
 225     Whether or not to enable role lookups. It defaults to true; set it to 0
 226     if you want to always avoid role lookups.
 227
 228   role_basedn
 229     This should be the basedn where the LDAP Objects representing your roles
 230     are.
 231
 232   role_filter
 233     This should be the LDAP Search filter to use during the role lookup. It
 234     defaults to '(memberUid=%s)'. The %s in this filter is replaced with the
 235     value of the "role_value" configuration option.
 236
 237     So, if you had a role_value of "cn", then this would be populated with
 238     the cn of the User's LDAP object. The special case is a role_value of
 239     "dn", which will be replaced with the User's DN.
 240
 241   role_scope
 242     This specifies the scope of the search for the user's role lookup. Valid
 243     values are "base", "one", and "sub". Defaults to "sub".
 244
 245   role_field
 246     Should be set to the Attribute of the Role Object's returned during Role
 247     lookup you want to use as the "name" of the role. Defaults to "CN".
 248
 249   role_value
 250     This is the attribute of the User object we want to use in our
 251     role_filter. If this is set to "dn", we will use the User Objects DN.
 252
 253   role_search_options
 254     This takes a hashref. It will append it's values to the call to
 255     Net::LDAP's "search" method during the user's role lookup. See Net::LDAP
 256     for valid options.
 257
 258     Be careful not to specify:
 259
 260         filter
 261         scope
 262         base
 263
 264     As they are already taken care of by other configuration options.
 265
 266   role_search_as_user
 267     By default this setting is false, and the role search will be performed
 268     by binding to the directory with the details in the *binddn* and
 269     *bindpw* fields. If this is set to false, then the role search will
 270     instead be performed when bound as the user you authenticated as.
 271
 272   entry_class
 273     The name of the class of LDAP entries returned. This class should exist
 274     and is expected to be a subclass of Net::LDAP::Entry
 275
 276   user_class
 277     The name of the class of user object returned. By default, this is
 278     Catalyst::Authentication::Store::LDAP::User.
 279
 280 METHODS
 281   new
 282     This method will populate "default_auth_store" in
 283     Catalyst::Plugin::Authentication with this object.
 284
 285 AUTHORS
 286     Adam Jacob <holoway@cpan.org>
 287
 288     Some parts stolen shamelessly and entirely from
 289     Catalyst::Plugin::Authentication::Store::Htpasswd.
 290
 291     Currently maintained by Peter Karman <karman@cpan.org>.
 292
 293 THANKS
 294     To nothingmuch, ghenry, castaway and the rest of #catalyst for the help.
 295     :)
 296
 297 SEE ALSO
 298     Catalyst::Authentication::Store::LDAP,
 299     Catalyst::Authentication::Store::LDAP::User,
 300     Catalyst::Authentication::Store::LDAP::Backend,
 301     Catalyst::Plugin::Authentication, Net::LDAP
 302
 303 COPYRIGHT & LICENSE
 304     Copyright (c) 2005 the aforementioned authors. All rights reserved. This
 305     program is free software; you can redistribute it and/or modify it under
 306     the same terms as Perl itself.
 307