Debian Codegraph @

README

raw
1 krb5-sync 3.1
2 (Kerberos Active Directory synchronization plugin)
3
4 Maintained by Russ Allbery <[email protected]>
5
6 Copyright 2015 Russ Allbery <[email protected]>. Copyright 2006, 2007,
7 2010, 2011, 2012, 2013 The Board of Trustees of the Leland Stanford
8 Junior University. Originally developed by Derrick Brashear and Ken
9 Hornstein of Sine Nomine Associates, on behalf of Stanford University.
10 This software is distributed under a BSD-style license. Please see the
11 section LICENSE below for more information.
12
13 BLURB
14
15 krb5-sync is a toolkit for synchronizing passwords and account status
16 from an MIT or Heimdal Kerberos master KDC to Active Directory.
17 Password changes are done via the Kerberos password change protocol, and
18 account status is updated via LDAP. It provides a plugin for the kadmin
19 libraries and supporting command-line utilities, as well as a patch for
20 Heimdal to add plugin support.
21
22 DESCRIPTION
23
24 Large organizations may not have the luxury of running a single Kerberos
25 KDC, or may need to maintain an MIT or Heimdal Kerberos environment in
26 parallel with Active Directory during a transition. This toolkit allows
27 one to run an MIT or Heimdal Kerberos KDC as the master password store,
28 create separate user accounts in an independent Active Directory, and
29 synchronize password updates and some account flag updates automatically
30 between the environments. It assumes that the MIT or Heimdal Kerberos
31 KDC is the only place changes will be made and those changes will be
32 replicated to the other environments. Bidirectional replication is
33 outside the scope of this toolkit.
34
35 This code is running in production at Stanford, but will likely require
36 modifications to fit any other environment. Feedback and improvements
37 will be gratefully accepted.
38
39 This toolkit consists of three basic pieces:
40
41 * A plugin that pushes password changes and selected account flag
42 changes to Active Directory. This is done using a separate keytab
43 for authentication. Active Directory password updates are done via
44 the Kerberos set-password protocol and status updates are done via
45 LDAP.
46
47 * A set of command-line utilities that can perform the same password
48 and status updates as the plugin but from the command-line. These
49 can be used to process failed synchronizations later, to test the
50 system, or to make manual changes as required.
51
52 * Patches to Heimdal to add a plugin system for password changes and
53 account status updates. MIT Kerberos 1.9 and later do not require
54 patching, and earlier versions of MIT Kerberos are not supported.
55 These patches add hooks that are run before and after password
56 changes, principal creations, and changes to principals. The code
57 added by these patches to libkadm5srv is independent of what that
58 plugin might do.
59
60 The plugin and system are designed so that operations done in the hook
61 prior to the password change can abort the password change if they fail.
62 The plugin provided here changes passwords in Active Directory prior to
63 the password change in the local KDC database. This means that if
64 Active Directory is unreachable or rejects the password change for some
65 reason, the whole operation will be rejected and the user's password
66 will not be changed in MIT Kerberos or Heimdal as well. This matches
67 the desired behavior for Stanford University; you may wish to modify it
68 for your site.
69
70 Currently, only one Active Directory realm is supported for updates.
71
72 REQUIREMENTS
73
74 The utilities provided in this package will work without any
75 modifications to your KDC or kadmind, but to use this entire system, you
76 will either need MIT Kerberos 1.9 or later or apply the patch in the
77 patches directory to Heimdal and rebuild. Due to how kadmind is
78 constructed, the changes are actually in the libkadm5srv library, not
79 the kadmind binary, so you'll need to install the modified libraries.
80 It is my hope that eventually the hooks necessary to do this will be
81 incorporated into the Heimdal distribution as well, and these tools will
82 be modified to support the Heimdal interfaces, and then patching will
83 not be necessary.
84
85 To build the account status update code, you will need OpenLDAP
86 installed. To authenticate to Active Directory, you will also need
87 Cyrus SASL installed including the Kerberos GSSAPI modules. The plugin
88 or command-line utilities will need access to a keytab with
89 administrative privileges in Active Directory. To configure status
90 updates, you will also need to know the server to which to do LDAP
91 queries (generally, this is one of the Domain Controllers).
92
93 The krb5-sync-backend utility program to manipulate the change queue
94 requires the IPC::Run and Net::Remctl::Backend Perl modules. The first
95 is available from CPAN. The latter is part of the remctl distribution,
96 available from:
97
98 http://www.eyrie.org/~eagle/software/remctl/
99
100 To run the full test suite, Perl 5.6.2 or later is required, as well as
101 the prerequisites for krb5-sync-backend. The following additional Perl
102 modules will be used if present:
103
104 Perl6::Slurp
105 Test::MinimumVersion
106 Test::Perl::Critic
107 Test::Pod
108 Test::Spelling
109 Test::Strict
110
111 All are available on CPAN. Those tests will be skipped if the modules
112 are not available.
113
114 To enable tests that may be sensitive to the local environment or that
115 produce a lot of false positives without uncovering many problems, set
116 RRA_MAINTAINER_TESTS to a true value.
117
118 To bootstrap from a Git checkout, or if you change the Automake files
119 and need to regenerate Makefile.in, you will need Automake 1.11 or
120 later. For bootstrap or if you change configure.ac or any of the m4
121 files it includes and need to regenerate configure or config.h.in, you
122 will need Autoconf 2.64 or later. For bootstrap, you will also need
123 Libtool. Perl is also required to generate the manual pages from a
124 fresh Git checkout.
125
126 INSTALLATION
127
128 First, for Heimdal, patch Heimdal with one of the patches provided in
129 the patches directory and install the new libkadm5srv library. See
130 patches/README for more information about the patches. If you're using
131 a different version of MIT Kerberos or Heimdal, you may need to adjust
132 the patch accordingly.
133
134 Then, you can build and install the plugin and command-line utilities
135 with the standard commands:
136
137 ./configure
138 make
139 make install
140
141 Pass --enable-silent-rules to configure for a quieter build (similar to
142 the Linux kernel). Use make warnings instead of make to build with full
143 GCC compiler warnings (requires a relatively current version of GCC).
144
145 By default, the plugin is installed as:
146
147 /usr/local/lib/krb5/plugins/kadm5_hook/krb5_sync.so
148
149 and the utilities are installed in /usr/local/sbin. The last step will
150 probably have to be done as root. To install in a different location,
151 specify the location with the --prefix option to configure.
152 Alternately, --libdir, --sbindir, and --mandir can be given to change
153 the installation locations of the binaries and manual pages separately.
154 The plugin is installed in krb5/plugins/kadm5_hook relative to libdir.
155
156 If /usr/bin/perl is not the path to Perl on your system, you will need
157 to change the first line of krb5-sync-backend. You will also need to
158 change the path to the krb5-sync utility in that script unless you
159 install krb5-sync in /usr/sbin.
160
161 Use --with-ldap to specify the prefix installation location of OpenLDAP
162 if it's not on the compiler's normal search paths. Or, alternately, use
163 --with-ldap-include and --with-ldap-lib to point to the include files
164 and libraries directly if OpenLDAP isn't installed under a single prefix
165 directory.
166
167 Normally, configure will use krb5-config to determine the flags to use
168 to compile with your Kerberos libraries. If krb5-config isn't found, it
169 will look for the standard Kerberos libraries in locations already
170 searched by your compiler. If the the krb5-config script first in your
171 path is not the one corresponding to the Kerberos libraries you want to
172 use or if your Kerberos libraries and includes aren't in a location
173 searched by default by your compiler, you need to specify the flags
174 --with-krb5=PATH and --with-kadm-server=PATH:
175
176 ./configure --with-krb5=/usr/pubsw --with-kadm-server=/usr/pubsw
177
178 You can also individually set the paths to the include directory and the
179 library directory with --with-krb5-include and --with-krb5-lib, and with
180 --with-kadm-server-include and --with-kadm-server-lib. You may need to
181 do this if Autoconf can't figure out whether to use lib, lib32, or lib64
182 on your platform. Note that these settings aren't used if a krb5-config
183 script is found.
184
185 To specify a particular krb5-config script to use, either set the
186 KRB5_CONFIG environment variable or pass it to configure like:
187
188 ./configure KRB5_CONFIG=/path/to/krb5-config
189
190 To not use krb5-config and force library probing even if there is a
191 krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:
192
193 ./configure KRB5_CONFIG=/nonexistent
194
195 You can pass the --enable-reduced-depends flag to configure to try to
196 minimize the shared library dependencies encoded in the binaries. This
197 omits from the link line all the libraries included solely because the
198 Kerberos libraries depend on them and instead links the programs only
199 against libraries whose APIs are called directly. This will only work
200 with shared Kerberos libraries and will only work on platforms where
201 shared libraries properly encode their own dependencies (such as Linux).
202 It is intended primarily for building packages for Linux distributions
203 to avoid encoding unnecessary shared library dependencies that make
204 shared library migrations more difficult. If none of the above made any
205 sense to you, don't bother with this flag.
206
207 TESTING
208
209 A basic test suite is available, but for right now only tests some of
210 the machinery and API and does some rudimentary testing of the change
211 queuing system. You can run it with:
212
213 make check
214
215 If a test fails, you can run a single test with verbose output via:
216
217 tests/runtests -o <name-of-test>
218
219 Do this instead of running the test program directly since it will
220 ensure that necessary environment variables are set up.
221
222 CONFIGURATION
223
224 Additional configuration is required to tell the plugin and command-line
225 tools what to do. The basic operations are configured by adding a
226 krb5-sync sub-section to the [appdefaults] section of /etc/krb5.conf (or
227 wherever your Kerberos libraries look for krb5.conf). Here's an
228 example:
229
230 krb5-sync = {
231 ad_keytab = /etc/krb5kdc/ad-keytab
232 ad_principal = service/[email protected]
233 ad_realm = WINDOWS.EXAMPLE.COM
234 ad_admin_server = dc1.windows.example.com
235 ad_ldap_base = ou=People,dc=windows,dc=example,dc=com
236 ad_instances = root ipass
237 ad_base_instance = windows
238 ad_queue_only = false
239
240 queue_dir = /var/spool/krb5-sync
241 syslog = true
242 }
243
244 It is possible to add realm-specific configuration here following the
245 normal krb5.conf syntax, but be aware that the plugin only looks for
246 configuration for the default realm, not for the realm of the affected
247 principal. In other words, it's not possible to have multiple
248 configurations based on the realm of the principal affected.
249
250 The configuration options are:
251
252 ad_admin_server
253
254 The host to contact via LDAP to push account status changes. If not
255 set, status changes will not be synchronized, only password changes.
256
257 ad_base_instance
258
259 If ad_base_instance is set, then any password change for a
260 single-component principal (such as [email protected]) will be
261 handled somewhat specially.
262
263 First, the instance set in ad_base_instance will be added and a
264 check against the local Kerberos database will be done to see if
265 that instance (in this case, user/[email protected]) exists. If
266 it doesn't, the password change is processed as normal. If it does,
267 the password change will be ignored. Instead, if the password for
268 user/[email protected] is changed, that will be propagated as the
269 password for the main account in Active Directory (in this case,
270 [email protected]).
271
272 This allows the Active Directory principal to be linked to a
273 separate instance, rather than the main account, in the MIT or
274 Heimdal Kerberos realm for particular users.
275
276 ad_instances
277
278 Specifies which instances should have passwords and account status
279 propagated to the Active Directory environment. By default, only
280 principals no instances (single-part principals) are propagated.
281 You can list a specific set of instances (space-separated), which
282 will then also be propagated to Active Directory.
283
284 The ad_instances option is only used by the plugin and is not used
285 by the command-line utility. Any principals passed to the
286 command-line utility will be acted on, even if they have non-empty
287 instances.
288
289 ad_keytab
290
291 Specifies the location of a keytab for authenticating to the Active
292 Directory other realm. Must be set.
293
294 ad_ldap_base
295
296 Specifies the root DN of the tree inside Active Directory where
297 account information is stored. If not set, status changes will not
298 be synchronized, only password changes.
299
300 ad_principal
301
302 Specifies the principal to authenticate as (using the key in the
303 keytab). Must be set.
304
305 ad_queue_only
306
307 Controls whether we attempt to push changes directly to Active
308 Directory or always queue them. It can be set to true to write all
309 changes to the queue where they can be processed later (by
310 krb5-sync-backend, for example). This may be helpful if the delay
311 from pushing changes to Active Directory causes problems for clients
312 (such as kpasswd clients, which are aggressive about retries and
313 don't like long delays).
314
315 ad_realm
316
317 Specifies the foreign realm. If ad_realm is not set, the plugin
318 will not attempt to push changes to Active Directory, so you can
319 deactivate this plugin while still loading it by removing that part
320 of the configuration.
321
322 queue_dir
323
324 Specifies where to queue changes that couldn't be made. If password
325 changes fail in AD, the whole password change is failed, but status
326 changes are done before synchronization with AD is attempted. The
327 queuing mechanism is used to be sure that failed changes aren't lost
328 and can be investigated further. For more information, see the man
329 page for krb5-sync and krb5-sync-backend. Must be set.
330
331 A setting of /var/spool/krb5-sync is recommended, since that's the
332 default path in krb5-sync-backend. If you use a different path,
333 you'll want to either change the path in that script or always use
334 the -d option.
335
336 syslog
337
338 Whether or not to log errors, warnings, and informational messages
339 from the plugin to syslog. By default, this is enabled. Set this
340 configuration option to false to suppress this logging, in which
341 case the only logging will be for errors returned to the kadmind or
342 kpasswdd servers.
343
344 With MIT Kerberos 1.9 or later, support for kadmind plugins is built in.
345 To load this plugin, add the following to the kdc.conf or krb5.conf file
346 used by kadmind:
347
348 [plugins]
349 kadm5_hook = {
350 module = sync:/usr/local/lib/krb5/plugins/kadm5_hook/sync.so
351 }
352
353 You may wish to install sync.so under a krb5/plugins/kadm5_hook in the
354 library directory used for your Kerberos installation instead, if that
355 is not /usr/local/lib, in which case you can use "kadm5_hook/sync.so" as
356 the relative path to the plugin.
357
358 The kadmind patch for Heimdal adds a configuration option for the
359 krb5.conf file in the [kadmin] section. If this option is not set, the
360 plugin will not be loaded and none of the hooks will be run. Therefore,
361 to use the plugin, add configuration like:
362
363 [kadmin]
364 hook_libraries = /usr/local/lib/krb5/plugins/kadm5_hook/sync.so
365
366 to the configuration file used by kadmind and kpasswdd. Update the path
367 for wherever the krb5-sync plugin is located.
368
369 ACTIVE DIRECTORY SETUP
370
371 You need to create an Active Directory user account to be used by the
372 krb5-sync software. (In Windows 2003 Active Directory, user accounts
373 can be objects of type "user" or "inetOrgPerson".) To be able to set
374 passwords, this account needs to be granted the Extended Right "Reset
375 Password" on user account objects in the Active Directory. To be able
376 to do account enabling and disabling, this account must be able to
377 locate the user object, usually done by granting "Read" access, and
378 write the userAccountControl attribute on user account objects.
379
380 If you have a cross-realm trust in place with your MIT Kerberos or
381 Heimdal realm, the AD account can be mapped to an account in the MIT or
382 Heimdal realm by setting the altSecurityIdentities property on the AD
383 user account object. This can be set using the "Name Mappings" feature
384 in Active Directory Users and Computers to add a Kerberos name.
385
386 From AD Users & Computers:
387
388 * Select "View" and make sure that "Advanced Features" is checked.
389
390 * Right-Click on the action account and select "Name Mappings".
391
392 * Under "Kerberos Names", add the principal name of the MIT account that
393 maps to this account.
394
395 If you do not have a cross-realm trust or want to use the AD account
396 directly instead of through a mapping, then you can export the account
397 using the ktpass command from the Windows support tools:
398
399 ktpass.exe -out <filename> -princ <principal name> -pass <AD password>
400 -mapuser <AD user account name>
401
402 (all on one line).
403
404 Thanks to Ross Wilper for this setup information.
405
406 HOMEPAGE AND SOURCE REPOSITORY
407
408 The krb5-sync web page at:
409
410 http://www.eyrie.org/~eagle/software/krb5-sync/
411
412 will always have the current version of this package, the current
413 documentation, and pointers to any additional resources.
414
415 krb5-sync is maintained using Git. You can access the current source by
416 cloning the repository at:
417
418 git://git.eyrie.org/devel/krb5-sync.git
419
420 or view the repository via the web at:
421
422 http://git.eyrie.org/?p=devel/krb5-sync.git
423
424 Please send any bug reports, patches, or questions to [email protected].
425
426 LICENSE
427
428 The krb5-sync package as a whole is covered by the following copyright
429 statement and license:
430
431 Copyright 2015 Russ Allbery <[email protected]>
432 Copyright 2006, 2007, 2008, 2010, 2011, 2012, 2013
433 The Board of Trustees of the Leland Stanford Junior University
434
435 Permission is hereby granted, free of charge, to any person obtaining a
436 copy of this software and associated documentation files (the
437 "Software"), to deal in the Software without restriction, including
438 without limitation the rights to use, copy, modify, merge, publish,
439 distribute, sublicense, and/or sell copies of the Software, and to
440 permit persons to whom the Software is furnished to do so, subject to
441 the following conditions:
442
443 The above copyright notice and this permission notice shall be included
444 in all copies or substantial portions of the Software.
445
446 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
447 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
448 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
449 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
450 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
451 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
452 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
453
454 All individual files without an explicit exception below are released
455 under this license. Some files may have additional copyright holders as
456 noted in those files. There is detailed information about the licensing
457 of each file in the LICENSE file in this distribution.
458
459 Some files in this distribution are individually released under
460 different licenses, all of which are compatible with the above general
461 package license but which may require preservation of additional
462 notices. All required notices are preserved in the LICENSE file. Each
463 file intended for copying into other software packages contains a
464 copyright and license notice at the top or bottom of the file. Please
465 take note of any attribution and notice requirements specified in that
466 license.