Commit | Line | Data |
a93dbce7 |
1 | NAME |
2 | Catalyst::Authentication::Store::LDAP - Authentication from an LDAP |
3 | Directory. |
fa35fd6f |
4 | |
a93dbce7 |
5 | SYNOPSIS |
6 | use Catalyst qw( |
7 | Authentication |
8 | ); |
fa35fd6f |
9 | |
a93dbce7 |
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))", |
57d476f1 |
40 | user_scope => "one", # or "sub" for Active Directory |
58b695ab |
41 | user_search_options => { |
42 | deref => 'always', |
43 | attrs => [qw( distinguishedname name mail )], |
44 | }, |
a93dbce7 |
45 | user_results_filter => sub { return shift->pop_entry }, |
439924cb |
46 | persist_in_session => 'all', |
a93dbce7 |
47 | }, |
48 | }, |
49 | }, |
50 | }, |
51 | ); |
fa35fd6f |
52 | |
a93dbce7 |
53 | sub login : Global { |
54 | my ( $self, $c ) = @_; |
fa35fd6f |
55 | |
a93dbce7 |
56 | $c->authenticate({ |
58b695ab |
57 | id => $c->req->param("login"), |
58 | password => $c->req->param("password") |
a93dbce7 |
59 | }); |
60 | $c->res->body("Welcome " . $c->user->username . "!"); |
61 | } |
fa35fd6f |
62 | |
a93dbce7 |
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. |
fa35fd6f |
67 | |
a93dbce7 |
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. |
fa35fd6f |
72 | |
a93dbce7 |
73 | It authenticates users in two steps: |
fa35fd6f |
74 | |
a93dbce7 |
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. |
fa35fd6f |
78 | |
a93dbce7 |
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. |
fa35fd6f |
81 | |
a93dbce7 |
82 | CONFIGURATION OPTIONS |
83 | Configuring with YAML |
84 | Set Configuration to be loaded via Config.yml in YourApp.pm |
fa35fd6f |
85 | |
a93dbce7 |
86 | use YAML qw(LoadFile); |
87 | use Path::Class 'file'; |
fa35fd6f |
88 | |
a93dbce7 |
89 | __PACKAGE__->config( |
90 | LoadFile( |
91 | file(__PACKAGE__->config->{home}, 'Config.yml') |
92 | ) |
93 | ); |
fa35fd6f |
94 | |
a93dbce7 |
95 | Settings in Config.yml (adapt these to whatever configuration format you |
96 | use): |
fa35fd6f |
97 | |
a93dbce7 |
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 |
58b695ab |
138 | user_filter: (sAMAccountName=%s) |
57d476f1 |
139 | user_scope: sub |
a93dbce7 |
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 it's 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 | } |
934094a2 |
228 | |
a93dbce7 |
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 it's 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 | |
439924cb |
277 | persist_in_session |
d7ddb040 |
278 | Can take one of the following values, defaults to *username*: |
439924cb |
279 | |
d7ddb040 |
280 | username |
439924cb |
281 | Only store the username in the session and lookup the user and its roles |
282 | on every request. That was how the module worked until version 1.015 and |
283 | 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 up |
287 | in the store after login. |
288 | |
289 | NOTE: It's recommended to limit the user attributes fetched from LDAP |
290 | using user_search_options / attrs to not exhaust the session store.. |
291 | |
a93dbce7 |
292 | entry_class |
293 | The name of the class of LDAP entries returned. This class should exist |
294 | and is expected to be a subclass of Net::LDAP::Entry |
295 | |
296 | user_class |
297 | The name of the class of user object returned. By default, this is |
298 | Catalyst::Authentication::Store::LDAP::User. |
299 | |
300 | METHODS |
301 | new |
302 | This method will populate "default_auth_store" in |
303 | Catalyst::Plugin::Authentication with this object. |
304 | |
305 | AUTHORS |
306 | Adam Jacob <holoway@cpan.org> |
307 | |
308 | Some parts stolen shamelessly and entirely from |
309 | Catalyst::Plugin::Authentication::Store::Htpasswd. |
310 | |
311 | Currently maintained by Peter Karman <karman@cpan.org>. |
312 | |
313 | THANKS |
314 | To nothingmuch, ghenry, castaway and the rest of #catalyst for the help. |
315 | :) |
316 | |
317 | SEE ALSO |
318 | Catalyst::Authentication::Store::LDAP, |
319 | Catalyst::Authentication::Store::LDAP::User, |
320 | Catalyst::Authentication::Store::LDAP::Backend, |
321 | Catalyst::Plugin::Authentication, Net::LDAP |
322 | |
323 | COPYRIGHT & LICENSE |
324 | Copyright (c) 2005 the aforementioned authors. All rights reserved. This |
325 | program is free software; you can redistribute it and/or modify it under |
326 | the same terms as Perl itself. |
fa35fd6f |
327 | |