krb5-sync 3.1
(Kerberos Active Directory synchronization plugin)
Maintained by Russ Allbery <eagle@eyrie.org>
Copyright 2015 Russ Allbery <eagle@eyrie.org>. Copyright 2006, 2007,
2010, 2011, 2012, 2013 The Board of Trustees of the Leland Stanford
Junior University. Originally developed by Derrick Brashear and Ken
Hornstein of Sine Nomine Associates, on behalf of Stanford University.
This software is distributed under a BSD-style license. Please see the
section LICENSE below for more information.
BLURB
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.
DESCRIPTION
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 is running in production at Stanford, but will likely require
modifications to fit any other environment. Feedback and improvements
will be gratefully accepted.
This toolkit consists of three basic pieces:
* A plugin that pushes password changes and selected account flag
changes to Active Directory. This is done using a separate keytab
for authentication. Active Directory password updates are done via
the Kerberos set-password protocol and status updates are done via
LDAP.
* A set of command-line utilities that can perform the same password
and status updates as the plugin but from the command-line. These
can be used to process failed synchronizations later, to test the
system, or to make manual changes as required.
* Patches to Heimdal to add a plugin system for password changes and
account status updates. MIT Kerberos 1.9 and later do not require
patching, and earlier versions of MIT Kerberos are not supported.
These patches add hooks that are run before and after password
changes, principal creations, and changes to principals. The code
added by these patches to libkadm5srv is independent of what that
plugin might do.
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.
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.
It is my hope that eventually the hooks necessary to do this will be
incorporated into the Heimdal distribution as well, and these tools will
be modified to support the Heimdal interfaces, and then patching will
not be necessary.
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,
available from:
http://www.eyrie.org/~eagle/software/remctl/
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:
Perl6::Slurp
Test::MinimumVersion
Test::Perl::Critic
Test::Pod
Test::Spelling
Test::Strict
All are available on CPAN. Those tests will be skipped if the modules
are not available.
To enable tests that may be sensitive to the local environment or that
produce a lot of false positives without uncovering many problems, set
RRA_MAINTAINER_TESTS to a true value.
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.
INSTALLATION
First, for Heimdal, patch Heimdal with one of the patches provided in
the patches directory and install the new libkadm5srv library. See
patches/README for more information about the patches. If you're using
a different version of MIT Kerberos or Heimdal, you may need to adjust
the patch accordingly.
Then, you can build and install the plugin and command-line utilities
with the standard commands:
./configure
make
make install
Pass --enable-silent-rules to configure for a quieter build (similar to
the Linux kernel). Use make warnings instead of make to build with full
GCC compiler warnings (requires a relatively current version of GCC).
By default, the plugin is installed as:
/usr/local/lib/krb5/plugins/kadm5_hook/krb5_sync.so
and the utilities are installed in /usr/local/sbin. The last step will
probably have to be done as root. To install in a different location,
specify the location with the --prefix option to configure.
Alternately, --libdir, --sbindir, and --mandir can be given to change
the installation locations of the binaries and manual pages separately.
The plugin is installed in krb5/plugins/kadm5_hook relative to libdir.
If /usr/bin/perl is not the path to Perl on your system, you will need
to change the first line of krb5-sync-backend. You will also need to
change the path to the krb5-sync utility in that script unless you
install krb5-sync in /usr/sbin.
Use --with-ldap to specify the prefix installation location of OpenLDAP
if it's not on the compiler's normal search paths. Or, alternately, use
--with-ldap-include and --with-ldap-lib to point to the include files
and libraries directly if OpenLDAP isn't installed under a single prefix
directory.
Normally, configure will use krb5-config to determine the flags to use
to compile with your Kerberos libraries. If krb5-config isn't found, it
will look for the standard Kerberos libraries in locations already
searched by your compiler. If the the krb5-config script first in your
path is not the one corresponding to the Kerberos libraries you want to
use or if your Kerberos libraries and includes aren't in a location
searched by default by your compiler, you need to specify the flags
--with-krb5=PATH and --with-kadm-server=PATH:
./configure --with-krb5=/usr/pubsw --with-kadm-server=/usr/pubsw
You can also individually set the paths to the include directory and the
library directory with --with-krb5-include and --with-krb5-lib, and with
--with-kadm-server-include and --with-kadm-server-lib. You may need to
do this if Autoconf can't figure out whether to use lib, lib32, or lib64
on your platform. Note that these settings aren't used if a krb5-config
script is found.
To specify a particular krb5-config script to use, either set the
KRB5_CONFIG environment variable or pass it to configure like:
./configure KRB5_CONFIG=/path/to/krb5-config
To not use krb5-config and force library probing even if there is a
krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:
./configure KRB5_CONFIG=/nonexistent
You can pass the --enable-reduced-depends flag to configure to try to
minimize the shared library dependencies encoded in the binaries. This
omits from the link line all the libraries included solely because the
Kerberos libraries depend on them and instead links the programs only
against libraries whose APIs are called directly. This will only work
with shared Kerberos libraries and will only work on platforms where
shared libraries properly encode their own dependencies (such as Linux).
It is intended primarily for building packages for Linux distributions
to avoid encoding unnecessary shared library dependencies that make
shared library migrations more difficult. If none of the above made any
sense to you, don't bother with this flag.
TESTING
A basic test suite is available, but for right now only tests some of
the machinery and API and does some rudimentary testing of the change
queuing system. You can run it with:
make check
If a test fails, you can run a single test with verbose output via:
tests/runtests -o <name-of-test>
Do this instead of running the test program directly since it will
ensure that necessary environment variables are set up.
CONFIGURATION
Additional configuration is required to tell the plugin and command-line
tools what to do. The basic operations are configured by adding a
krb5-sync sub-section to the [appdefaults] section of /etc/krb5.conf (or
wherever your Kerberos libraries look for krb5.conf). Here's an
example:
krb5-sync = {
ad_keytab = /etc/krb5kdc/ad-keytab
ad_principal = service/sync@WINDOWS.EXAMPLE.COM
ad_realm = WINDOWS.EXAMPLE.COM
ad_admin_server = dc1.windows.example.com
ad_ldap_base = ou=People,dc=windows,dc=example,dc=com
ad_instances = root ipass
ad_base_instance = windows
ad_queue_only = false
queue_dir = /var/spool/krb5-sync
syslog = true
}
It is possible to add realm-specific configuration here following the
normal krb5.conf syntax, but be aware that the plugin only looks for
configuration for the default realm, not for the realm of the affected
principal. In other words, it's not possible to have multiple
configurations based on the realm of the principal affected.
The configuration options are:
ad_admin_server
The host to contact via LDAP to push account status changes. If not
set, status changes will not be synchronized, only password changes.
ad_base_instance
If ad_base_instance is set, then any password change for a
single-component principal (such as user@EXAMPLE.COM) will be
handled somewhat specially.
First, the instance set in ad_base_instance will be added and a
check against the local Kerberos database will be done to see if
that instance (in this case, user/windows@EXAMPLE.COM) exists. If
it doesn't, the password change is processed as normal. If it does,
the password change will be ignored. Instead, if the password for
user/windows@EXAMPLE.COM is changed, that will be propagated as the
password for the main account in Active Directory (in this case,
user@WINDOWS.EXAMPLE.COM).
This allows the Active Directory principal to be linked to a
separate instance, rather than the main account, in the MIT or
Heimdal Kerberos realm for particular users.
ad_instances
Specifies which instances should have passwords and account status
propagated to the Active Directory environment. By default, only
principals no instances (single-part principals) are propagated.
You can list a specific set of instances (space-separated), which
will then also be propagated to Active Directory.
The ad_instances option is only used by the plugin and is not used
by the command-line utility. Any principals passed to the
command-line utility will be acted on, even if they have non-empty
instances.
ad_keytab
Specifies the location of a keytab for authenticating to the Active
Directory other realm. Must be set.
ad_ldap_base
Specifies the root DN of the tree inside Active Directory where
account information is stored. If not set, status changes will not
be synchronized, only password changes.
ad_principal
Specifies the principal to authenticate as (using the key in the
keytab). Must be set.
ad_queue_only
Controls whether we attempt to push changes directly to Active
Directory or always queue them. It can be set to true to write all
changes to the queue where they can be processed later (by
krb5-sync-backend, for example). This may be helpful if the delay
from pushing changes to Active Directory causes problems for clients
(such as kpasswd clients, which are aggressive about retries and
don't like long delays).
ad_realm
Specifies the foreign realm. If ad_realm is not set, the plugin
will not attempt to push changes to Active Directory, so you can
deactivate this plugin while still loading it by removing that part
of the configuration.
queue_dir
Specifies where to queue changes that couldn't be made. If password
changes fail in AD, the whole password change is failed, but status
changes are done before synchronization with AD is attempted. The
queuing mechanism is used to be sure that failed changes aren't lost
and can be investigated further. For more information, see the man
page for krb5-sync and krb5-sync-backend. Must be set.
A setting of /var/spool/krb5-sync is recommended, since that's the
default path in krb5-sync-backend. If you use a different path,
you'll want to either change the path in that script or always use
the -d option.
syslog
Whether or not to log errors, warnings, and informational messages
from the plugin to syslog. By default, this is enabled. Set this
configuration option to false to suppress this logging, in which
case the only logging will be for errors returned to the kadmind or
kpasswdd servers.
With MIT Kerberos 1.9 or later, support for kadmind plugins is built in.
To load this plugin, add the following to the kdc.conf or krb5.conf file
used by kadmind:
[plugins]
kadm5_hook = {
module = sync:/usr/local/lib/krb5/plugins/kadm5_hook/sync.so
}
You may wish to install sync.so under a krb5/plugins/kadm5_hook in the
library directory used for your Kerberos installation instead, if that
is not /usr/local/lib, in which case you can use "kadm5_hook/sync.so" as
the relative path to the plugin.
The kadmind patch for Heimdal adds a configuration option for the
krb5.conf file in the [kadmin] section. If this option is not set, the
plugin will not be loaded and none of the hooks will be run. Therefore,
to use the plugin, add configuration like:
[kadmin]
hook_libraries = /usr/local/lib/krb5/plugins/kadm5_hook/sync.so
to the configuration file used by kadmind and kpasswdd. Update the path
for wherever the krb5-sync plugin is located.
ACTIVE DIRECTORY SETUP
You need to create an Active Directory user account to be used by the
krb5-sync software. (In Windows 2003 Active Directory, user accounts
can be objects of type "user" or "inetOrgPerson".) To be able to set
passwords, this account needs to be granted the Extended Right "Reset
Password" on user account objects in the Active Directory. To be able
to do account enabling and disabling, this account must be able to
locate the user object, usually done by granting "Read" access, and
write the userAccountControl attribute on user account objects.
If you have a cross-realm trust in place with your MIT Kerberos or
Heimdal realm, the AD account can be mapped to an account in the MIT or
Heimdal realm by setting the altSecurityIdentities property on the AD
user account object. This can be set using the "Name Mappings" feature
in Active Directory Users and Computers to add a Kerberos name.
From AD Users & Computers:
* Select "View" and make sure that "Advanced Features" is checked.
* Right-Click on the action account and select "Name Mappings".
* Under "Kerberos Names", add the principal name of the MIT account that
maps to this account.
If you do not have a cross-realm trust or want to use the AD account
directly instead of through a mapping, then you can export the account
using the ktpass command from the Windows support tools:
ktpass.exe -out <filename> -princ <principal name> -pass <AD password>
-mapuser <AD user account name>
(all on one line).
Thanks to Ross Wilper for this setup information.
HOMEPAGE AND SOURCE REPOSITORY
The krb5-sync web page at:
http://www.eyrie.org/~eagle/software/krb5-sync/
will always have the current version of this package, the current
documentation, and pointers to any additional resources.
krb5-sync is maintained using Git. You can access the current source by
cloning the repository at:
git://git.eyrie.org/devel/krb5-sync.git
or view the repository via the web at:
http://git.eyrie.org/?p=devel/krb5-sync.git
Please send any bug reports, patches, or questions to eagle@eyrie.org.
LICENSE
The krb5-sync package as a whole is covered by the following copyright
statement 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.
All individual files without an explicit exception below are released
under this license. Some files may have additional copyright holders as
noted in those files. There is detailed information about the licensing
of each file in the LICENSE file in this distribution.
Some files in this distribution are individually released under
different licenses, all of which are compatible with the above general
package license but which may require preservation of additional
notices. All required notices are preserved in the LICENSE file. Each
file intended for copying into other software packages contains a
copyright and license notice at the top or bottom of the file. Please
take note of any attribution and notice requirements specified in that
license.