                              krb5-sync 2.2
            (Kerberos Active Directory synchronization plugin)

              Maintained by Russ Allbery <rra@stanford.edu>

  Copyright 2006, 2007, 2010, 2011, 2012 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
  file LICENSE in the distribution for more information.

  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.

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 and older versions of MIT Kerberos 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 toolkit consists of three basic pieces:

   * Patches to MIT Kerberos (prior to 1.9; 1.9 and later do not require
     patching) and Heimdal to add a plugin system for password changes and
     account status updates.  These patches add hooks that are run prior
     to a password change, after a password change, and after a change to
     an account's flags.  The code in libkadm5srv is independent of what
     that plugin might do.

   * A plugin that uses that system to push 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.

  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.

  Be aware that, due to the structure of the MIT Kerberos libkadm5srv
  code, the patch for versions prior to 1.9 runs the pre-commit hook and
  hence password propagation to Active Directory before the password is
  checked for reuse.  This means that the password may be changed in
  Active Directory but then rejected by the local KDC if it is present in
  the account's password history.  If you remember only one password in
  the password history, this will be harmless, since it will only mean the
  Active Directory password will be reset to the existing password.  If,
  however, you store multiple passwords in the password history, the
  passwords could end up being desynchronized.  This should be fixed in
  MIT Kerberos 1.9.

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 MIT Kerberos or 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 an interface like this will be
  incorporated into the Heimdal distribution as well and 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).

  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, patch MIT Kerberos or Heimdal with the patch provided in the
  patches directory if necessary and install the new libkadm5srv or
  libkadm5srv_mit library.  See patches/README for more information about
  the patch.  If you're using a different version of MIT Kerberos, 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).

  The plugin is installed as /usr/local/lib/krb5/plugins/krb5_sync.so by
  default, 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.

  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
  --with-krb5=PATH:

      ./configure --with-krb5=/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.  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 rudimentary test suite is available, but for right now only tests the
  portability and utility libraries and the documentation.  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
          ad_instances    = root ipass

          queue_dir       = /var/spool/krb5-sync
      }

  The ad_keytab option specifies the location of a srvtab or keytab for
  authenticating to the other realm, the ad_principal option specifies the
  principal to authenticate as (using the key in the srvtab or keytab),
  and the ad_realm option specifies the foreign realm.  ad_admin_server is
  the host to contact via LDAP to push account status changes.
  ad_ldap_base specifies the base tree inside Active Directory where
  account information is stored.  Omit the trailing "dc=" part; it will be
  added automatically from ad_realm.  The default is "dc=Accounts".

  The ad_instances option specifies which instances have passwords and
  account status propagated to that environment.  By default, all
  principals with non-empty instances are not propagated.  You can list a
  specific set of instances (space-separated) which are propagated to the
  AD environment.  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.

  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.

  The queue_dir setting 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.  If you use a queue
  directory other than the one given, you will need to change the
  beginning of the krb5-sync-backend script as well.

  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 = krb5_sync:/usr/local/lib/krb5/plugins/krb5_sync.so
          }

  You may wish to install krb5_sync.so under a krb5/plugins/kadm5_hook in
  the library directory used for your Kerberos installation instead, in
  which case you can use "kadm5_hook/krb5_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/krb5_sync.so

  to the configuration file used by kadmind and kpasswdd.  Update the path
  for wherever the krb5-sync plugin is located.

  The kadmind patch for older versions of MIT adds a similar configuration
  option for the kdc.conf.  To use the plugin on older versions of MIT,
  add a line like:

      pwupdate_plugin = /usr/local/lib/krb5/plugins/krb5_sync.so

  to the local realm sub-section of the [realms] section.

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.
