| < kadmin-remctl Design | Russ Allbery > Software > kadmin-remctl | ksetpass Manual Page > |
(remctl interface to kadmin functionality)
kadmin-backend change_passwd user old new
kadmin-backend check_passwd user password
kadmin-backend create user password (enabled | disabled)
kadmin-backend (delete | disable | enable | examine) user
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
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 three 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 Kerberos v5, 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_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 Kerberos v5, 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
Kerberos v5, NOTGS in the AFS kaserver, or a userAccountControl of 514 in
Active Directory.
The enable function clears DISALLOW_ALL_TIX on the principal in
Kerberos v5, 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 v5 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 Kerberos
v5 is the result of kadmin getprinc. A line of 40 dashes separates
the first from the second if AFS kaserver support is configured.
The help function prints out a summary of supported functions and
their arguments.
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.
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 Kerberos v5, 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.
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:
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). Each value should be a hash containing one or more of the
following keys:
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.
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.
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.
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.
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.
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.
Principal to use for AFS kaserver operations. If this key is not set, no propagation of operations to an AFS kaserver environment is attempted.
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 Kerberos v5 output, even if AFS kaserver integration is otherwise configured. This is probably only of interest at Stanford University to support an old API.
Srvtab to use for AFS kaserver authentication.
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.
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, and be sure it rejects any characters that might confuse the shell or kadmin (shell metacharacters, whitespace, and so forth).
Set to a true value if passwords for this instance should be subject to password strength checking, false otherwise.
Principal to use for authentication of Kerberos v5 kadmin operations. If this key is not set, no propagation of operations to an MIT Kerberos v5 KDC is done. If this key is set, Kerberos v5 operations are preferred over Active Directory operations and kadmin-backend assumes that account status changes and password changes will be propagated from Kerberos v5 to Active Directory by means other than this program.
If set, pass this argument to Kerberos v5 kadmin via the -s flag to tell it to use a different admin server. Mostly useful for testing to point kadmin-backend at a different kadmin server.
Keytab to use for authentication of Kerberos v5 kadmin operations.
Set to a true value if kadmin-backend should support resetting
passwords for this instance (via the instance reset function),
false otherwise.
Path to the regular MIT Kerberos v5 kadmin command-line client. Most operations are done by running this client interactively under Expect.
Path to the Kerberos v5 kpasswd command-line client, which is used
to implement the change_passwd function.
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.
Path to kasetkey, used to make changes to an AFS kaserver. By default, kadmin-backend searches the PATH for the first kasetkey binary found.
Path to ksetpass, used to set passwords in Active Directory. By default, kadmin-backend searches the PATH for the first ksetpass binary found.
Path to ldapadd, used to create new accounts in Active Directory. By default, kadmin-backend searches the PATH for the first ldapadd binary found.
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.
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.
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.
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.
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 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.
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.
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.
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/>.
Russ Allbery <rra@stanford.edu>
| < kadmin-remctl Design | Russ Allbery > Software > kadmin-remctl | ksetpass Manual Page > |