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