kuseradmin
General form:
kuseradmin add username -c "Real Name" -s "/bin/shell" -d "/users/home/directory" -g "groupname"
kuseradmin mod username -c "Real Name" -s "/bin/shell" -d "/users/home/directory" -g "groupname"
kuseradmin del username
kuseradmin isadmin
kuseradmin isprotected
kuseradmin password username
kuseradmin crreset username
kuseradmin crdelete username
kuseradmin crallow username [allow/deny/none]
kuseradmin verify username servicename timestamp signature [...]
kuseradmin test [uid/permissions]
kuseradmin version
The kuseradmin utility provides a restricted interface for non-root users to manage users and reset passwords on a system, according to options in /etc/kcml/kuseradmin.conf.
When setting up a KCML system, the kuseradmin binary should be root owned and have the setuid flag - this can be set up with:
chown root kuseradmin chmod 755 kuseradmin chmod +s kuseradmin
To check, run kuseradmin test uid: it should have output of the form
uid: 1234 (brian) euid: 0 (root)
where the uid line gives the user ID of the running user.
The config file /etc/kcml/kuseradmin.conf (see following section) should be root owned and neither group- nor world-readable. This can be set up with:
chown root /etc/kcml/kuseradmin.conf chmod 644 /etc/kcml/kuseradmin.conf
/etc/kcml/kuseradmin.conf defines settings for the kuseradmin command, and contains the list of who has admin rights over which users. It is important that this file and all directory components are owned by root and have owner-only write access.
The following example kuseradmin.conf demonstrates the format:
############################################################################### # kuseradmin.conf - settings for kuseradmin # # This file defines various settings for the kuseradmin command, including # who is allowed to use it, length of randomly generated passwords, characters # allowed in passwords, etc. # # Syntax: # # # lines beginning with # are comments and are ignored # # admin user1[,user2[,user3...]] pattern[,pattern2[,pattern3...]] # says that user1, user2, etc. are allowed to add, modify, delete, and # reset the passwords of users matching any of the patterns, where * in # the patterns matches any text, and ? in the patterns matches any one # character # # examples: # admin john adp* # admin paul,george ?????123 # admin ringo adp*,?????123 # # pwlen number # says that randomly generated passwords will contain the specified # number of characters # # examples: # pwlen 8 # pwlen 12 # # pwchars string # allows randomly generated passwords to contain only characters from # string (if your password policy requires numbers or punctuation, for # example) # # examples: # pwchars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ # pwchars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 # # protect user # adds the user pattern to an internal list that kuseradmin will # refuse to modify, where patterns support * and ? in the same way as # the admin directive (a number of defaults, such as root, are always # in this list) # # examples: # protect gdm # protect *daemon # # tsage number # for kuseradmin verify, specifies the maximum age (in seconds) a # signature's timestamp is allowed to be before it will be rejected - # a value of 0 will disable age checking. Defaults to 8 hours. # # examples: # tsage 0 # tsage 3600 # ############################################################################### admin brian * admin john adp*,kcc* admin paul,george,ringo adp* protect sgtpepper pwlen 8 pwchars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
When adding or changing users with add or mod, the following optional command line options are available. All are optional.
| Flag | Purpose |
|---|---|
| -c "Real Name" | Specifies the comment field for the user at the operating system level, traditionally used for real name. If unspecified, this is left blank. |
| -s shell | Sets the login shell for the user at the operating system level. If unspecified, the user's shell will be made the same as the calling user's shell. |
| -d directory | Specifies the user's home directory at the operating system level. If unspecified, or directory is caller, the user's home directory will be made the same as the calling user. |
| -g group | Specifies the user's primary group at the operating system level. If unspecified, the user is given the same primary group as the user running kuseradmin. |
When calling kuseradmin programatically, the following return codes may be tested for:
| Value | Meaning |
|---|---|
| 0 | Success. |
| 11 | Failed with given input |
| 12 | Permission denied |
| 13 | Configuration error (may be in kuseradmin.conf or wider operating system setup) |
| 14 | Operating system error |
| 15 | Signature verification failed |
When calling kuseradmin isadmin or kuseradmin isprotected, the following return codes may be tested for:
| Value | Meaning |
|---|---|
| 0 | The calling user has no admin rights over any users/is not protected. This corresponds to KCML FALSE. |
| 1 | The calling user has admin rights over some users/is protected. This corresponds to KCML TRUE. |
More detailed information will be available on standard output, including failure messages of OS utilities (useradd, etc).
kuseradmin add username -c "Real Name" -s "/bin/shell" -d "/users/home/directory" -g "groupname"
kuseradmin add can be used to add UNIX users to a system.
kuseradmin mod username -c "Real Name" -s "/bin/shell" -d "/users/home/directory" -g "groupname"
kuseradmin mod can be used to modify the details of UNIX users in a system.
kuseradmin del username
kuseradmin del can be used to delete a user from a UNIX system. It will also completely remove the users' record in the challenge/response database, if one exists.
kuseradmin isadmin
kuseradmin isadmin prints no output, but has a shell return code of 0 if the user is not a kuseradmin administrator, and a shell return code of 1 if the user is a kuseradmin administrator.
See also: Testing admin rights with KCML
kuseradmin isprotected
kuseradmin isprotected prints no output, but has a shell return code of 0 if the user is not protected, and a shell return code of 1 if the user is protected.
kuseradmin password username
kuseradmin password may be used to reset a users' password.
kuseradmin crreset username
kuseradmin crreset may be used to reset a users' challenge/response data. This will clear their locale, email address, SMS number, and answers for all questions. It will leave their challenge/response permissions intact.
kuseradmin crdelete username
kuseradmin crdelete may be used to remove a users' challenge/response data. This may be useful for testing during installation.
kuseradmin crallow username [allow/deny/none]
kuseradmin crallow may be used to change a users' challenge/response permissions.
If set to allow, the user will be prompted for challenge/response answers upon logging into a KCML service if they have not already provided some, and will be offered an opportunity to reset their password if they supply an incorrect one.
If set to deny, the user will not be prompted for challenge/response answers upon logging into a KCML service, and will not be offered an opportunity to reset their password if they supply an incorrect one.
none is the same policy as deny, but may be useful in distinguishing between users who have been forbidden from using challenge/response (for example, users with access to sensitive data) and users for whom no decision has been made yet (for example, a first-time login).
deny will work even on protected users.
kuseradmin verify username service timestamp signature [...]
When using a custom HTTP endpoint to manage password reset requests, KClient will send a request containing the username, the service, a timestamp, and a signature. kuseradmin verify checks that the signature is valid for the supplied data. If it is, kuseradmin will return with exit status 0; otherwise, it will return with exit status 15.
Optionally, another kuseradmin action may be supplied after the signature. If the signature is successfully verified, the action will then be carried out. The username for the action must match the username from the signature.
Examples:
kuseradmin verify kcc AUTOLINE1234 "2016-09-15 09:10:48.000001" 5f9516...fc1da3 kuseradmin verify kcc AUTOLINE1234 "2016-09-15 09:10:48.000001" 5f9516...fc1da3 password kcc
kuseradmin test [uid/permissions]
kuseradmin test supplies some information which may be useful for testing during installation.
kuseradmin test uid will print the running users' uid (which may be anything) and effective uid (which should be root).
kuseradmin test permissions will attempt to display the admin permissions from kuseradmin.conf.
See also: Installation
See also: kuseradmin.conf
kuseradmin version
kuseradmin version will show the installed version of kuseradmin and may be useful for testing an installation. This may differ from the installed versions of the connection manager and KCML.
To test whether the current user has admin rights (for example, to decide whether to show admin-related menu options), kuseradmin isadmin may be invoked programmatically with KCML with code like this:
IF (SHELL "kuseradmin isadmin")
PRINT "User has some admin rights."
ELSE
PRINT "User has no admin rights."
END IF
To allow or forbid a user from requesting a password reset using challenge/response, kuseradmin crallow user allow or kuseradmin crallow user deny may be used.
To reset a user's challenge/response data (nag lock-out, or they've forgotten their answers), kuseradmin crreset user may be used - this will leave their allowed status, locale, SMS number, and email address (if configured) intact. If it is necessary to clear these too, use kuseradmin crdelete user, which will completely erase their challenge/response information.
To manage users or reset passwords, kuseradmin may be invoked programmatically with KCML with code like this:
DIM output$80, buf$80, lastline$80, h, i
$DEVICE /D10 = "kuseradmin password testuser2 |"
SELECT #10 /D10
STR($OPTIONS #10, 2, 1) = OR HEX(01)
output$ = ""
WHILE TRUE DO
lastline$ = buf$
buf$ = ""
h = READ #10, buf$
IF (END)
BREAK
END IF
REDIM output$ = $PRINTF("%s%s", output$, buf$)
WEND
IF (STR(lastline$,, 8) <> "SUCCESS:")
PRINT "an error occured"
ELSE
PRINT $PRINTF("new password is %s", STR(lastline$, 9))
END IF
Important to note here are that the last line of the output will always be either an error message from kuseradmin or of the form SUCCESS:sometext, where sometext is either a generated password, useradd, usermod, or userdel depending on the operation.
As of versions 07.15.01.23251, 07.16.01.23251, and 07.17.00.23251, kuseradmin for AIX has additional restrictions on the security attributes of users for modifying operations (mod, del, password).
If a user's account_locked attribute is set, kuseradmin will exit with status 12 (permission denied) with the following message:
kuseradmin: can not modify user kcc because account is locked
where kcc is the user under consideration.
If a user's unsuccessful_login_count attribute is greater than or equal to their loginretries attribute, kuseradmin will exit with status 12 (permission denied) with the following message:
kuseradmin: can not modify user kcc because account has too many unsuccessful logins
where kcc is the user under consideration.
If kuseradmin is not working as you expect, check syslog (see Configuring the syslog daemon).
If syslog contains a warning of the form:
config file has unsafe file permissions - going forward with minimal permissions
then ensure that the file permissions on /etc/kcml/kuseradmin.conf and all directory components are secure; they should all be owned by root and only root should be able to write to them.