def reset_password(self, args):
"""Resets the password of the authenticated, or a specified User.
If a user is specified, and the authenticated user is an Administrator,
this will reset the password of the specified user to the provided value.
If no user is specified, the password of the authenticated user will be changed.
NOTE: to prevent accidental change of an Administrators password, an extra trap is in place:
* the username (or id) MUST be provided, even if the authenticated user
is the user being changed.
Required Arguments:
* `password` - the new password.
* - OR -
* `generate` - generate a random password.
Optional Arguments:
* `user` - Either the User ID or Name.
Returns: Success message if successful, error messages on failure.
"""
user = args.get("user")
new_pw = args.get("password")
generate = catocommon.is_true(args.get("generate"))
# this is a admin function, kick out
if user and not api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_msg="Only Administrators can perform this function.")
# the only way to reset an "Administrator" role password
# is to BE an Administrator and SPECIFY a user, even if the user is you
if not user and api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_detail="Administrators must specify a user to change.")
if not new_pw and not generate:
return R(err_code=R.Codes.Exception, err_detail="A password must be provided, or 'generate' must be true.")
obj = catouser.User()
obj.FromName(user)
if obj.ID:
# if a password was provided, or the random flag was set...exclusively
if new_pw:
# if the user requesting the change *IS* the user being changed...
# set force_change to False
force = True
if obj.ID == api._USER_ID:
force = False
obj.ChangePassword(new_password=new_pw, force_change=force)
elif generate:
obj.ChangePassword(generate=generate)
else:
return R(err_code=R.Codes.GetError, err_detail="Unable to update password.")
catocommon.write_change_log(api._USER_ID, catocommon.CatoObjectTypes.User, obj.ID, obj.FullName, "Password change/reset via API.")
return R(response="[%s] password operation successful." % obj.FullName)
def update_user(self, args):
"""Updates a user account.
Only an 'Administrator' can manage other users. If the credentials used for this API call
are not an Administrator, the call will not succeed.
Properties will only be updated if the option is provided. Omitted properties will not be changed.
NOTE: the "username" of a user cannot be changed.
If a user has 'locked' their account by numerous failed login attempts, the flag is reset
by setting any property. It's easiest to just the status to 'enabled'.
Required Arguments:
* `user` - ID or Name of the User to update.
Optional Arguments:
* `name` - The full name of the user.
* `role` - The users role. (Valid values: Administrator, Developer, User)
* `email` - Email address for the user. Can be cleared with "None".
* `authtype` - 'local' or 'ldap'.
* `forcechange` - Require user to change password on next login. (Valid values: 'true' or 'false')
* `status` - Status of the account. (Valid values: enabled, disabled, locked)
* `expires` - Expiration date for this account. Must be in mm/dd/yyyy format. Can be cleared with "None".
* `groups` - Add to the list of groups the user belongs to. Group names cannot contain spaces. Comma delimited list.
* `password` - the new password.
* - OR -
* `generate` - generate a random password.
Returns: A [User Object](restapi/api-response-objects.html#User){:target="_blank"}.
"""
# this is a admin function, kick out
if not api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_msg="Only Administrators can perform this function.")
# define the required parameters for this call
required_params = ["user"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
obj = catouser.User()
obj.FromName(args["user"])
if not obj.ID:
return R(err_code=R.Codes.GetError, err_detail="Cannot find User.")
# first, we have a procedure for changing password
new_pw = args.get("password")
generate = catocommon.is_true(args.get("generate"))
if new_pw:
obj.ChangePassword(new_password=new_pw)
elif generate:
obj.ChangePassword(generate=generate)
# now we can change the properties
# these can't be null or empty
obj.FullName = args.get("name", obj.FullName)
obj.AuthenticationType = args.get("authtype", obj.AuthenticationType)
obj.Role = args.get("role", obj.Role)
obj.Status = args.get("status", obj.Status)
# these can be set to null/empty
obj.Expires = args.get("expires", obj.Expires)
obj.Email = args.get("email", obj.Email)
obj.Email = None if obj.Email.lower() == "none" else obj.Email
# this is always reset from the API... one less argument to mess with.
obj.FailedLoginAttempts = 0
# these are figured out manually
# force change
if args.get("forcechange"):
obj.ForceChange = 1 if args["forcechange"] == "true" else 0
"""
OK this group stuff is a little tricky. User.DBUpdate requires us to send in the complete list of Groups we want.
1) the User object already has a list, self.Tags, of all the tags it has.
2) the caller might have sent a COMPLETE list of tags (from the UI), or only a list to ADD (from the API)
doesn't really matter.
So, we:
a) MERGE self.Tags with self._Groups, we'll get a distinct list of all groups we HAD or want to ADD
b) delete all tags
c) insert our new merged list
"""
groups = args.get("groups").split(",") if args.get("groups") else []
if obj.Tags is not None:
groups = obj.Tags + groups # merge the lists
obj._Groups = list(set(groups)) # make it distinct
# all the properties are set... call DBUpdate!
if obj.DBUpdate():
catocommon.write_change_log(api._USER_ID, catocommon.CatoObjectTypes.User, obj.ID, obj.FullName, "User updated via API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def WriteObjectChangeLog(oType, sObjectID, sObjectName, sLog=""):
catocommon.write_change_log(GetSessionUserID(), oType, sObjectID, sObjectName, sLog)