krb5-sync

The best of all rulers is but a shadowy presence to his subjects.
Next comes the ruler they love and praise;
Next comes the one they fear;
Next comes one with whom they take liberties.
When there is not enough faith, there is lack of good faith.
Hesitant, he does not utter words lightly.
When his task is accomplished and his work done
The people all say, "It happened to us naturally."

Lao Tzu, Tao Te Chin (translated by D.C. Lau)

Warning

This package is orphaned. Although I believe it is still useful, I no longer need to synchronize with Active Directory and am no longer maintaining this package. If you would like to pick up maintenance of it, please feel free. Contact me if you would like this page to redirect to its new home.

Description

krb5-sync is a toolkit for synchronizing passwords and account status from an MIT or Heimdal Kerberos master KDC to Active Directory. Password changes are done via the Kerberos password change protocol, and account status is updated via LDAP. It provides a plugin for the kadmin libraries and supporting command-line utilities, as well as a patch for Heimdal to add plugin support.

Large organizations may not have the luxury of running a single Kerberos KDC, or may need to maintain an MIT or Heimdal Kerberos environment in parallel with Active Directory during a transition. This toolkit allows one to run an MIT or Heimdal Kerberos KDC as the master password store, create separate user accounts in an independent Active Directory, and synchronize password updates and some account flag updates automatically between the environments. It assumes that the MIT or Heimdal Kerberos KDC is the only place changes will be made and those changes will be replicated to the other environments. Bidirectional replication is outside the scope of this toolkit.

This code was running in production at Stanford when I left in 2014 (and probably still is), but will likely require modifications to fit any other environment.

This toolkit consists of three basic pieces:

The plugin and system are designed so that operations done in the hook prior to the password change can abort the password change if they fail. The plugin provided here changes passwords in Active Directory prior to the password change in the local KDC database. This means that if Active Directory is unreachable or rejects the password change for some reason, the whole operation will be rejected and the user's password will not be changed in MIT Kerberos or Heimdal as well. This matches the desired behavior for Stanford University; you may wish to modify it for your site.

Currently, only one Active Directory realm is supported for updates.

This software was written by Derrick Brashear and Ken Hornstein of Sine Nomine Associates on behalf of Stanford University. I subsequently reorganized, updated, hacked, and otherwise modified it significantly.

Requirements

The utilities provided in this package will work without any modifications to your KDC or kadmind, but to use this entire system, you will either need MIT Kerberos 1.9 or later or apply the patch in the patches directory to Heimdal and rebuild. Due to how kadmind is constructed, the changes are actually in the libkadm5srv library, not the kadmind binary, so you'll need to install the modified libraries.

To build the account status update code, you will need OpenLDAP installed. To authenticate to Active Directory, you will also need Cyrus SASL installed including the Kerberos GSSAPI modules. The plugin or command-line utilities will need access to a keytab with administrative privileges in Active Directory. To configure status updates, you will also need to know the server to which to do LDAP queries (generally, this is one of the Domain Controllers).

The krb5-sync-backend utility program to manipulate the change queue requires the IPC::Run and Net::Remctl::Backend Perl modules. The first is available from CPAN. The latter is part of the remctl distribution.

To run the full test suite, Perl 5.6.2 or later is required, as well as the prerequisites for krb5-sync-backend. The following additional Perl modules will be used if present:

All are available on CPAN. Those tests will be skipped if the modules are not available.

To bootstrap from a Git checkout, or if you change the Automake files and need to regenerate Makefile.in, you will need Automake 1.11 or later. For bootstrap or if you change configure.ac or any of the m4 files it includes and need to regenerate configure or config.h.in, you will need Autoconf 2.64 or later. For bootstrap, you will also need Libtool. Perl is also required to generate the manual pages from a fresh Git checkout.

Download

The distribution:

krb5-sync 3.1 2015-08-19 tar.gz (PGP signature) tar.xz (PGP signature)

An archive of older releases is also available.

Debian packages are included in Debian 7.0 (wheezy) and later releases. Install krb5-sync-plugin for the KDC plugin and krb5-sync-tools for the supporting tools.

krb5-sync is maintained using the Git version control system. To check out the current development tree, clone:

    git://git.eyrie.org/kerberos/krb5-sync.git

You can also browse the current development source.

Documentation

User documentation:

Developer documentation:

License

The krb5-sync package as a whole is covered by the following copyright and license:

Copyright 2015 Russ Allbery <eagle@eyrie.org>
Copyright 2006, 2007, 2008, 2010, 2011, 2012, 2013 The Board of Trustees of the Leland Stanford Junior University

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Some individual source files are covered by other, compatible licenses. For complete copyright and license information, see the file LICENSE in the krb5-sync source distribution.

Last modified and spun 2015-11-01