< kadmin-remctl Change Summary | Russ Allbery > Software > Orphaned Software > kadmin-remctl | kadmin-backend-heim > |
(remctl interface to kadmin functionality)
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
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 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_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
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 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 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). 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:
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).
Contains extra options to pass to the kadmin addprinc
command when
creating a new principal. These can be any valid flags to the addprinc
command.
If set, the number of seconds into the future at which the password for a newly-created account should expire.
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 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.
If set, the given password policy will be set for all newly-created principals.
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 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.
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.
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.
Russ Allbery <eagle@eyrie.org>, based heavily on work by Roland Schemers.
Copyright 2003, 2007, 2008, 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.
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/>.
< kadmin-remctl Change Summary | Russ Allbery > Software > Orphaned Software > kadmin-remctl | kadmin-backend-heim > |