| Russ Allbery > Software > kadmin-remctl | kadmin-remctl Design > |
(remctl interface for Kerberos kadmin functions)
Written by Russ Allbery <rra@stanford.edu>
Copyright 1997, 2003, 2007, 2008 Board of Trustees, Leland Stanford Jr. University. This software is distributed under a BSD-style license. Please see the file LICENSE in the distribution for more information.
kadmin-remctl provides a remctl backend that implements basic Kerberos account administration functions (create, delete, enable, disable, reset password, examine) plus user password changes and a call to strength-check a given password. It can also provide similar management of instances and creation, deletion, and management of accounts in MIT Kerberos, Active Directory, and an AFS kaserver where appropriate. Also included is a client for privileged users to use for password resets. Many of the defaults and namespace checks are Stanford-specific, but it can be modified for other sites.
At Stanford, we at one time had three Kerberos realms: an MIT Kerberos v5 realm, an Active Directory realm, and an AFS kaserver Kerberos v4 realm. We also have middleware and web applications that support changing or resetting passwords, creating new accounts, examining principals, and enabling or disabling accounts based on affiliation changes. Rather than give all of these systems kadmin access (and force them to use kadmin clients, which is difficult since many are written in Java), and rather than forcing them to do realm synchronization themselves, we export an interface via remctl and use the Java remctl client to talk to that interface.
This package includes the kadmin backend, a Perl script that supports creating, deleting, enabling, and disabling accounts, changing or resetting passwords, and checking password strength. This script does synchronization to Active Directory and an AFS kaserver Kerberos v4 realm as well where appropriate. It also includes ksetpass, a simple client for changing passwords via the Kerberos password change protocol that doesn't prompt for the existing password like kpasswd. This client is used to set passwords in Active Directory.
Also included in this package is a C client for use by privileged users when changing passwords for others. This client searches for the user in a password file first to present the full name for verification, and then obtains special credentials for a designated principal and then contacts a remctl server on a non-standard port to issue a change password command. This is done on a non-standard port so that it can use a different principal for authentication than the regular host principal normally used by remctl and require that the privileged user reauthenticate before using this service.
Some aspects of this package are very Stanford-specific, most notably the sometimes-bizarre formatting of the output from this script (which is for compatibility with the legacy APIs used at Stanford). It is probably not suitable for using at other sites without modifications, but may provide ideas for how to do something similar for another site.
The AFS kaserver support should be considered frozen and is no longer tested since Stanford no longer runs a kaserver environment. It may be dropped from a future release if the code is significantly restructured.
For more information, see docs/design in the source distribution.
The kadmin backend is written in Perl and requires the Perl Expect module. It calls the MIT Kerberos v5 kadmin and kpasswd programs and therefore requires that they be available. For integration with the AFS kaserver Kerberos v4 realm, it uses kasetkey. The Kerberos v4 synchronization is disabled by default.
The kadmin backend can propagate instance creation and deletion to an Active Directory. To use this support, you will need the Perl Encode, MIME::Base64, and Text::Template modules. (Encode and MIME::Base64 come with Perl 5.8 and later.) You will also need k5start and the OpenLDAP binaries ldapadd, ldapdelete, and ldapmodify. You can get k5start from:
The passwd_change C client requires the C libremctl library be available to build (plus, obviously, a C compiler). It also requires a Kerberos library; either MIT Kerberos or Heimdal should be sufficiant (although currently the client will produce much better error messages using MIT Kerberos).
ksetpass requires a Kerberos library; either MIT Kerberos or Heimdal should be sufficient.
Finally, the backend is intended to be run under remctld and use remctl to handle authentication, privacy, and integrity.
remctl is available from:
kasetkey is available as part of the wallet distribution at:
This software should not be deployed as-is at any site other than Stanford. It needs to be reviewed and modified for changing local assumptions, paths, and integration requirements.
There are two components: the remctl backend and remctld configuration for the interface, and the passwd_change client program. The remctl backend script is a Perl script and doesn't require compilation. It loads its defaults from /etc/kadmin-remctl.conf; see its man page for more details on the configuration options, most of which must be set. remctl configuration fragments suitable for being included in your remctld configuration are in the remctl subdirectory. The kadmin fragment provides the general interface.
To set up the server for the passwd_change client, create a special designated principal in your Kerberos database, set the DISALLOW_TGT_BASED flag on that principal to require manual authentication, and set the lifetime of that principal to one hour. Then, create a keytab for that principal on the host running the special server and set up a separate instance of remctld running on a different port that includes the remctl/password configuration fragment. That instance of remctl should be run with the KRB5_KTNAME environment variable set, pointing it at the keytab for this designated principal.
Before building the passwd_change client, you may want to modify the settings at the top of the passwd_change.c code to point it to the correct server and port and to use the correct designated principal for the password changing service. (If you don't, you'll have to always have appropriate configuration in your krb5.conf file.) Then, run:
./configure
make
make install
The last step will probably have to be done as root and will install both the client and the kadmin-backend script. You may need to change the path to Perl on the first line of kadmin-backend (as well as the other defaults in it). By default, kadmin-remctl installs itself under /usr/local; you can change that path by passing the --prefix=PATH argument to configure.
If the remctl libraries aren't installed in a directory searched by the compiler, use --with-remctl to specify the root directory (prefix) under which remctl was installed.
After installation, you may want to configure passwd_change in your krb5.conf files. See the passwd_change man page for configuration details.
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-kerberos=PATH:
./configure --with-kerberos=/usr/pubsw
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 build kadmin-remctl in a different directory from the source if you wish. To do this, create a new empty directory, cd to that directory, and then give the path to configure when running configure. Everything else should work as above.
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.
The kadmin-remctl web page at:
http://www.eyrie.org/~eagle/software/kadmin-remctl/
will always have the current version of this package, the current documentation, and pointers to any additional resources.
kadmin-remctl is maintained using Git. You can access the current source by cloning the repository at:
git://git.eyrie.org/kerberos/kadmin-remctl.git
or view the repository via the web at:
http://git.eyrie.org/?p=kerberos/kadmin-remctl.git
| Russ Allbery > Software > kadmin-remctl | kadmin-remctl Design > |