| Russ Allbery > Software > Orphaned Software > krb5-sync | krb5-sync Manual > |
(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.
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 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.
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.
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.
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.
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.
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.
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.
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.
| Russ Allbery > Software > Orphaned Software > krb5-sync | krb5-sync Manual > |