README

                              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.