iControl 101 - #07 - User Management

iControl is a robust management API that not only encompasses the control of network management objects, but also many other aspects of the system level configuration. This article will discuss the methods used to create and manage all aspects of system user accounts.

Creating a new user

First it will be helpful in looking at the portion of the administration GUI on the BIG-IP to get a context of what methods map to which properties of a user.

The "User Name" and "Password" fields are somewhat self explanatory.  The other fields likely need a bit of explanation.

Role

The role is the authorization role that you assign to this user.  The level you give will be dependent on what you want the user to have access to on the device.  Valid values are as follows:

• No Access - No access to the device.
• Guest - Read-only view on all objects and the ability to change their own password.
• Operator - Ability to enable and disable nodes and pool members.
• Application Editor -Ability to modify nodes, pools, pool members, and monitors.
• Application Security Policy Editor - Complete access to Application Security Manager (ASM) policy objects.
• Manager - Ability to create, modify, and delete virtual servers, nodes, profiles, monitors, and iRules.
• User Manager - Ability to create, modify, and delete non-admin local user accounts.
• Resource Administrator - Complete access to all objects on the system, except user account objects.
• Administrator - Full access to all objects in the system.

Partition Access

For version 9.4 and above, users can be assigned to a partition (another word for administrative domain).  This is the partition that the user can modify objects in.

Terminal Access

For all types of accounts, you can give access to the device from the command line through a ssh connection.  "Disabled" means ssh connections are not allowed.  "Advanced Shell" allows access to the unix bash shell. And, finally, "bigpipe shell" allows login access to F5's shell that supports bigpipe management commands.

Automation

So, how does one automate the management of users?  The UserManagement interface in the Management iControl module has all the methods you would need to create and modify the properties of the users. 

To create a new user, you'll want the create_user_2 method.  The "_2" methods allow support for encrypted passwords, so you'll likely want to use them in your applications.  The method prototype is:

Management::UserManagement::create_user_2(
  in Management::UserManagement::UserInfo2 [] users
);

struct Management::UserManagement::UserInfo2 {
  Management::UserManagement::UserID user;
  Management::UserManagement::UserRole role;
  Management::UserManagement::PasswordInfo password;
  String home_directory
  String login_shell
  long user_id
  long group_id
};
struct Management::UserManagement::UserID {
  String name;
  String full_name;
};
enum Management::UserManagement::UserRole {
  USER_ROLE_ADMINISTRATOR = 0,
  USER_ROLE_TRAFFIC_MANAGER = 1,
  USER_ROLE_GUEST = 2,
  USER_ROLE_ASM_POLICY_EDITOR = 3,
  USER_ROLE_INVALID = 4,
  USER_ROLE_MANAGER = 5,
  USER_ROLE_EDITOR = 6,
  USER_ROLE_APPLICATION_EDITOR = 7,
  USER_ROLE_CERTIFICATE_MANAGER = 8,
  USER_ROLE_USER_MANAGER = 9,
  USER_ROLE_RESOURCE_ADMINISTRATOR = 10
};
struct Management::UserManagement::PasswordInfo {
  boolean is_encrypted;
  String password;
};

Let's go by each of the fields in the UserInfo2 structure.

• user - you put the username (name and full name) in here.
• role - specify the authorization role that you would like this user to have.
• password - include the encrypted (with crypt()) or unencrypted plain text password here.
• home_directory - This is the home directory for the user.  It is typically in the format of /home/$username
• login_shell - This is what allows terminal access.  Use /bin/false for Disabled access, /bin/bash for the advanced shell, and /bin/bpsh for the bigpipe shell.
• user_id - Use a default value of 0.
• group_id - Use a default value of 500.

So, how do you set partition information?  That's the job for the Management::UserManagement::set_user_permissions() method.  If you want to assign the user to a specific partition, then you'll want to pass in that user's name along with the partition name and role for that partition you would like the user to have.

Management::UserManagement::set_user_permission(
    in String [] user_names,
    in Management::UserManagement::UserPermission [] [] permissions
);

struct Management::UserManagement::UserPermission {
  UserRole role;
  String partition;
}

Managing an existing user account

For an existing user account, you'll want to use the "get" and "set" methods for all of the user attributes.  I won't list the full prototypes out here, but this is a list of methods you have access to:

• change_my_password
• change_password
• change_password_2
• create_user
• create_user_2
• delete_user
• get_authentication_method
• get_default_partition
• get_default_role
• get_encrypted_password
• get_fullname
• get_group_id
• get_home_directory
• get_list
• get_login_shell
• get_my_permission
• get_remote_console_access
• get_role
• get_user_id
• get_user_permission
• get_version
• set_authentication_method
• set_default_partition
• set_default_role
• set_fullname
• set_group_id
• set_home_directory
• set_login_shell
• set_remote_console_access
• set_role
• set_user_id
• set_user_permission

Putting it together

Here is some sample code in C# showing how to automate the New User dialog in the administrative GUI using iControl:

void createUser (
  String sUsername,
  String sPassword,
  iControl.ManagementUserManagementUserRole role,
  String sPartition,
  bool bTerminalAccess
)
{
  iControl.ManagementUserManagementUserInfo2 userInfo = 
    new iControl.ManagementUserManagementUserInfo2();
  userInfo.user = new iControl.ManagementUserManagementUserID();
  userInfo.user.full_name = sUsername;
  userInfo.user.name = sUsername;
  userInfo.password = new iControl.ManagementUserManagementPasswordInfo();
  userInfo.password.is_encrypted = false;
  userInfo.password.password = sPassword;
  userInfo.role = role;
  userInfo.home_directory = "/home/" + sUsername;
  userInfo.login_shell = bTerminalAccess ? "/bin/bash" : "/bin/false";
  userInfo.user_id = 0;
  userInfo.group_id = 500;
  // m_interfaces is defined as a class variable in the calling application.
  m_interfaces.ManagementUserManagement.create_user_2(
    new iControl.ManagementUserManagementUserInfo2 [] { userInfo });
  if ((sPartition != null) && (sPartition.Length > 0) && (!sPartition.Equals("All")))
  {
    iControl.ManagementUserManagementUserPermission [][] userPerms = 
      new iControl.ManagementUserManagementUserPermission[1][];
    userPerms[0] = new iControl.ManagementUserManagementUserPermission[1];
    userPerms[0][0] = new iControl.ManagementUserManagementUserPermission();
    userPerms[0][0].partition = sPartition;
    userPerms[0][0].role = role;
    m_interfaces.ManagementUserManagement.set_user_permission(
      new String[] { sUsername }, userPerms);
  }
}

To individually modify each of the user attributes on an existing user, use the individual accessor methods defined in the Management::UserManagement interface in a way similar to how the set_user_permission method is used in the previous example.