| 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. |