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