kadmin-backend

(remctl interface to kadmin functionality)

SYNOPSIS

kadmin-backend change_passwd user old new

kadmin-backend check_expire user [expire | pwexpire]

kadmin-backend check_passwd user password

kadmin-backend create user password (enabled | disabled)

kadmin-backend (delete | disable | enable | examine) user

kadmin-backend expiration user (date | now | never)

kadmin-backend pwexpiration user (date | now | never)

kadmin-backend (reset_passwd | reset) user password

kadmin-backend instance check user instance

kadmin-backend instance create user instance password

kadmin-backend instance delete user instance

kadmin-backend instance list instance

kadmin-backend instance reset user instance password

DESCRIPTION

This script provides an interface to the same functionality provided by kadmin, but it also takes appropriate action to synchronize changes with the AFS kaserver Kerberos v4 realm and with Active Directory where appropriate or necessary. It also provides some additional functions that kadmin doesn't provide directly and has separate functions for handling account instances (principals in the form principal/instance).

All of these functions except for examine and the instance functions by default only accept principals with no instances or realms, and that consist of two to eight characters starting with a lowercase letter and containing only digits and lowercase letters. This can be overridden in the configuration. instance functions require a principal that fits the same requirements and an instance that starts with a letter and contains only lowercase alphanumeric characters. Principals may also be rejected if they're reserved, and explicit configuration is required for each instance (including the empty instance, for principals without an instance).

Whether an action will be performed in a Heimdal Kerberos KDC, Active Directory, or an AFS kaserver Kerberos v4 realm or some combination of the three is determined by the configuration.

The instance functions should only be used to manage instances that have regular passwords. Instances used by automated processes via keytabs should be managed via a different mechanism. All instance functions support additional ACL checking beyond the authorization rules of remctld to verify that the remote user is allowed to manage that particular instance.

The change_passwd function changes a user's password given the current password. It is equivalent to kpasswd but only works on the restricted set of users as described above.

The check_expire function returns the expiration time for either the account (when given the expire argument) or the password (when given the pwexpire argument) in ISO 8601 format (YYYY-MM-DD HH:MM:SSZ). If neither argument is given, the nearest expiration date is displayed. The time is always in the UTC time zone. If the account or password does not expire, the output will be empty.

The check_passwd function performs strength checking against the given password without changing the password. user is required for backward compatibility but is ignored. This function will exit successfully (exit status of 0) regardless of whether the password is acceptable; a non-zero exit status is only used for an internal error. If the password is acceptable, there is no output; if the password is not acceptable, the reason for its rejection is printed to standard output prefixed with retstr: and a space.

The create function creates a new principal with the given password. If the third argument is enabled, the new account is created enabled. If disabled, the new account is created with disallow-all-tix set in Heimdal, NOTGS in the AFS kaserver, and a userAccountControl of 514 in Active Directory.

The delete function deletes the given principal.

The disable function sets disallow-all-tix on the principal in Heimdal, NOTGS in the AFS kaserver, or a userAccountControl of 514 in Active Directory.

The enable function clears disallow-all-tix on the principal in Heimdal, NOTGS in the AFS kaserver, or sets a userAccountControl of 512 in Active Directory.

The examine function prints out information about the principal in Kerberos and, if configured, the AFS kaserver. It does not support Active Directory. This is the only function that accepts principals with instances. If AFS kaserver support is configured, it attempts to convert principals with an instance into their Kerberos v4 equivalent before looking them up there. The output format for the AFS kaserver is the same as the old Kerberos v4 kadmin output, and the output for Heimdal is the same as the MIT Kerberos kadmin getprinc output (even from a Heimdal KDC). A line of 40 dashes separates the first from the second if AFS kaserver support is configured.

The expiration function changes the expiration date of a principal. This is not propagated into an AFS kaserver or into Active Directory. The expiration date may be now, never, or something that can be parsed by the date parsing routines. Using the YYYY-MM-DD HH:MM:SS format is recommended.

The help function prints out a summary of supported functions and their arguments.

The pwexpiration function changes the expiration date of a principal's password. Unlike an account expiration, this expiration date will be pushed forward when the user changes their password. This is not propagated into an AFS kaserver or into Active Directory. The expiration date may be now, never, or something that can be parsed by the date parsing routines. Using the YYYY-MM-DD HH:MM:SS format is recommended.

The reset_passwd function changes the password for a given principal without requiring knowledge of the old password. Changing the password of a user who can themselves reset passwords is not permitted, and a separate blacklist of principals whose password cannot be changed is also supported. reset is supported as a synonym (used primarily with a separate password reset service).

The instance check function prints a message and returns 0 if that combination of principal and instance exists, or a different message and returns 1 if the instance does not exist.

The instance create function creates a new principal/instance Kerberos principal, provided that it doesn't already exist, and sets its password to the provided password. This principal may or may not have password checking enabled, depending on the configuration for that instance.

The instance delete function deletes a principal/instance Kerberos principal.

The instance list function lists all Kerberos principals with the given instance. This function only supports Heimdal, not Active Directory. Note that this list may contain service principals and other reserved principals that cannot be managed through this interface.

The instance reset function resets the password for a given principal/instance Kerberos principal, provided that password resets are allowed for that instance type in the kadmin-backend configuration.

This script is normally run via remctld with different ACLs on each supported function. reset_passwd is a special case and should normally be run via a separate instance of remctld listening on a different port and using a principal for authentication that disallows TGT-based service tickets and has a short lifetime.

CONFIGURATION

If the file /etc/kadmin-remctl.conf exists, kadmin-backend will load it after setting its configuration defaults. This file must be used to configure kadmin-backend; without configuration, it will not take any actions for most functions. The configuration file must be valid Perl syntax and should normally consist only of variable settings. The following Perl variables may be set:

%CONFIG

This is the general configuration for how each type of principal should be handled. Every instance managed by this installation of kadmin-backend needs to be configured here. Each key of this hash should be the name of an instance (possibly '' for the empty instance). The values for a key of '' will be used when examining principals with unknown instances, and if there is no configuration for '', examining such principals will not be allowed.

Each value should be a hash containing one or more of the following keys:

ad_config

Points to an OpenLDAP configuration file that's used for propagation of instance creation into Active Directory. If this key isn't set for an instance, no propagation into Active Directory will be attempted. This configuration file should set the LDAP server and any other required properties. An example:

    URI ldaps://dc1.example.org/
    BASE ou=accounts,dc=windows,dc=example,dc=org
    TLS_CACERT /etc/krb5kdc/ad-root-cert
    SASL_SECPROPS minssf=0,maxssf=0

See ldap.conf(5) for the available options.

Only GSS-API binds are supported by kadmin-backend at this time.

The above SASL_SECPROPS settings are required if you want to set passwords via the LDAP interface. Active Directory requires TLS be used when setting passwords over LDAP and does not allow a SASL security layer to be negotiated when TLS is in use. The above settings configure TLS and disable negotiation of a SASL security layer.

Even this doesn't work with Windows Server 2008, which rejects all GSS-API binds over TLS. For that version, change the URI to ldap instead of ldaps and remove the TLS and SASL_SECPROPS configuration. This will do straight GSS-API binds with a SASL security layer. Then, set ad_setpass as mentioned below so that password changes are done via the Kerberos set password protocol.

ad_group

Contains the DN of an Active Directory authorization group to which all created principals of the given instance should be added automatically on creation. The addition will be done by modifying the group identified by that DN to add a new member attribute equal to the DN of the newly created account.

ad_keytab

Points to a keytab used to obtain credentials for Active Directory modifications. This keytab will be used with k5start to obtain Kerberos credentials when running LDAP commands. If ad_config is set, this key is required.

ad_ldif

Points to a Text::Template template file containing the complete LDIF required to create a new entry in Active Directory for an account with the given instance. See Text::Template for the details of the format, but mostly all you'll need to do is include strings like {$principal} into the file where you want to substitute in the username. The available variables are:

    principal   The base username (without any instance)
    instance    The instance of the account
    password    The base64-encoded password for the account
    control     The userAccountControl setting

For example, this file may contain:

    dn: cn={$principal}/{$instance},ou=Accounts,dc=example,dc=org
    objectClass: user
    cn: {$user}/{$instance}
    sAMAccountName: {$principal}/{$instance}
    userAccountControl: {$control}
    unicodePwd:: {$password}
    userPrincipalName: {$principal}/{$instance}@EXAMPLE.ORG

For account creation, the entire template is used. For account deletion and modifications, only the line starting with dn: (and any LDIF continuation lines) is extracted and the contents, after template resolution, are used as the DN to delete from Active Directory.

If you don't have TLS set up so that you can set unicodePwd over the LDAP interface, set ad_setpass as described below.

ad_realm

The realm of the Active Directory environment. If this is set, ksetpass calls are qualified with this realm and k5start is told to authenticate to this realm when making LDAP calls. If the keytab used for Active Directory is a keytab in your local non-AD Kerberos realm and you're using cross-realm authentication with Active Directory, don't set this key.

ad_setpass

If this is set, accounts are created in Active Directory disabled and without a password, the password is set with ksetpass, and then the account is enabled. This is necessary if your Active Directory doesn't permit GSS-API authentication over TLS.

afs_admin

Principal to use for AFS kaserver operations. If this key is not set, no propagation of operations to an AFS kaserver environment is attempted.

afs_fake

Controls how the Kerberos v4 examine output is constructed. If this key is set to a true value, kadmin-backend will create fake Kerberos v4 kadmin examine output based on the Heimdal output, even if AFS kaserver integration is otherwise configured. This is probably only of interest at Stanford University to support an old API.

afs_srvtab

Srvtab to use for AFS kaserver authentication.

acl

The value is the ACL file listing the principals that can manage instances of this type. This option must be set and should contain a simple list of fully-qualified principals, one per line, or lines in the form:

    include /path/to/another/file

which are processed recursively.

allowed

The value is a regular expression that overrides the default regular expression used to check principals (the non-instance portion). Be sure that this regular expression doesn't allow an instance (instances are handled separately) or a realm.

checking

Set to a true value if passwords for this instance should be subject to password strength checking, false otherwise.

expiration

If set, the number of seconds into the future at which the password for a newly-created account should expire.

k5_admin

Principal to use for authentication of Kerberos kadmin operations. If this key is not set, no propagation of operations to a Heimdal KDC is done. If this key is set, Kerberos operations are preferred over Active Directory operations and kadmin-backend assumes that account status changes and password changes will be propagated from Kerberos to Active Directory by means other than this program.

k5_host

If set, connect to this server for kadmin operations instead of the default configured administrative server for that realm.

k5_keytab

Keytab to use for authentication of Kerberos kadmin operations.

locked

Set to an array containing a program (and its required arguments) to use to check if an instance is locked. "Locked" means that the instance cannot be enabled again using this interface for some policy reason. If the array is undefined or empty, there is no checking for locked status.

reset

Set to a true value if kadmin-backend should support resetting passwords for this instance (via the instance reset function), false otherwise.

$K5_KPASSWD

Path to the Kerberos kpasswd command-line client, which is used to implement the change_passwd function.

$K5START

Path to k5start, used to obtain credentials when propagating accounts into Active Directory. By default, kadmin-backend searches the PATH for the first k5start binary found.

$KASETKEY

Path to kasetkey, used to make changes to an AFS kaserver. By default, kadmin-backend searches the PATH for the first kasetkey binary found.

$KSETPASS

Path to ksetpass, used to set passwords in Active Directory. By default, kadmin-backend searches the PATH for the first ksetpass binary found.

$LDAPADD

Path to ldapadd, used to create new accounts in Active Directory. By default, kadmin-backend searches the PATH for the first ldapadd binary found.

$LDAPDELETE

Path to ldapdelete, used to obtain credentials when deleting accounts from Active Directory. By default, kadmin-backend searches the PATH for the first ldapdelete binary found.

$LDAPMODIFY

Path to ldapmodify, used to add principals to Active Directory authorization groups if the ad_group configuration option is set and to enable and disable principals. By default, kadmin-backend searches the PATH for the first ldapmodify binary found.

$LDAPSEARCH

Path to ldapsearch, used to check whether an account already exists in Active Directory. By default, kadmin-backend searches the PATH for the first ldapsearch binary found.

%RESERVED

A hash of reserved principal names (without instances). The keys are the principals; the value should be any true value. If a principal is present in this hash, kadmin-backend will refuse to perform any operation on that principal or any of its instances. You can either reset this hash completely in the configuration file (if you do, be careful of principals like kadmin and krbtgt) or add additional principals to it.

$RESET_ACL

Path to the ACL file controlling who can change passwords for other users. kadmin-backend checks the principal for which a password is being changed via the reset_passwd function against this file and refuses password changes if the target principal is listed in this file. This ensures that people who can change others' passwords cannot themselves have their password changed through that route, preventing privilege escalation.

$RESET_BLACKLIST

Path to a file containing additional principals whose passwords cannot be changed via the reset_passwd function. This file has the same syntax as the $RESET_ACL file.

$STRENGTH

The Kerberos principal used for strength checking. When checking the strength of a password (the check_passwd function), kadmin-backend attempts to change the password of this principal. This principal should therefore be set DISALLOW_ALL_TIX and not be used on any ACLs, since any user with access to the check_passwd function can change its password to anything they choose.

For the defaults, see the beginning of the kadmin-backend script.

ENVIRONMENT

REMOTE_USER

This environment variable must be set to the Kerberos principal attempting an operation when managing instances. The contents of this variable will be checked against the ACL file for that instance. This variable is normally set by the remctld server.

AUTHOR

Russ Allbery <eagle@eyrie.org>, based heavily on work by Roland Schemers. Original Heimdal port written by Jon Robertson <jonrober@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 2009, 2010, 2011, 2013, 2014 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.

SEE ALSO

k5start(1), kasetkey(8), ksetpass(1), ldap.conf(5), ldapadd(1), ldapdelete(1), ldapmodify(1), ldapsearch(1)

This program is part of kadmin-remctl. The current version is available from <http://www.eyrie.org/~eagle/software/kadmin-remctl/>.

Last spun 2014-07-26 from POD modified 2014-04-13