Control Access Using Roles

Use the SDK to create and configure the roles that control the permissions of your users and API keys. For example as part of your automated process for deploying Deep Security Manager, your code creates the various roles that are suitable for the tasks that users perform, or that you perform using the API.

Roles should provide the minimal rights that users or your code require to perform their tasks.

For background information about roles, see Define roles for users in the Deep Security Help Center.

The following classes enable you to interact with roles:

  • AdministratorRolesApi: Create, modify, delete, search, describe, and list roles
  • Role: Represents a role and provides access to role properties
  • Rights classes: Several classes that represent access rights for Deep Security resources. For example, ComputerRights defines rights for interacting with computers, and ScheduledTaskRights defines rights for interacting with scheduled tasks.

See also Obtain a role ID.

Create or modify a role

Create a role, or modify an existing role, that provides the permissions that your users or API keys need to perform their tasks. Use the following general steps to create or modify a role:

  1. Create a Role object and configure the properties:
    • Provide a name to identify the role and, optionally, a description
    • (Optional) Identify the computers and policies that the role can access
    • (Optional) Add rights objects that dictate which tasks the role can perform on the computers and policies that it can access.
  2. Create an AdministratorsRoleApi object and use it to create or modify the role on Deep Security Manager.

When you create a role, by default it has read access to all computers and policies, enables users to change their own password, and allows access to the Deep Security Manager console.

The following JSON represents an example data structure of a Role object:

  • The allComputers and allPolicies items indicate access to all computers and policies. If either are falsecomputerIDs and policyIDs items hold the IDs of the computers and policies that can be accessed
  • The rights item and its descendants correspond with the various rights classes that define access rights to Deep Security resources. To make this example concise, deeper levels of rights items are not shown.
{
    "name": "Auditor",
    "description": "",
    "urn": "urn:tmds:identity:us-east-ds-1:41342:role/Auditor",
    "immutable": false,
    "canOnlyManipulateUsersWithEqualOrLesserRights": false,
    "allComputers": true,
    "allPolicies": true,
    "allowUserInterface": true,
    "allowWebService": true,
    "rights": {
        "platformRights": {...},
        "antiMalwareRights": {...},
        "webReputationRights": {...},
        "firewallRights": {...},
        "intrusionPreventionRights": {...},
        "integrityMonitoringRights": {...},
        "logInspectionRights": {...},
        "applicationControlRights": {...},
        "hostedServiceRights": {...}
    },
    "ID": 2
}

To see the complete data structure of a Role object, see the response for the Describe an Administrator Role operation in the API Reference.

Example: Create a role with specific rights

The following example creates a role that can find computers, determine whether each computer has a policy assigned, and assigns a policy as needed. The Auditor role does not satisfy these requirements because it does not provide the rights for modifying computers.

Python
def create_role_for_computer_reports(api, configuration, api_version, api_exception):
    """ Creates a role with rights that are appropriate for reading computer properties and assigning policies to computers.

    :param api: The Deep Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Deep Security API exception module.
    :return: The ID of the new role.
    """

    # Create the Role object
    run_reports_role = api.Role()
    run_reports_role.name = "Computer Status and Properties"

    # No need for access to policies
    run_reports_role.all_policies = False

    # Add rights to edit computer properties
    computer_rights = api.ComputerRights()
    computer_rights.can_edit_computer_properties = True

    platform_rights = api.PlatformRights()
    platform_rights.computer_rights = computer_rights

    rights = api.Rights()
    rights.platform_rights = platform_rights

    # Add the rights to the role
    run_reports_role.rights = rights

    # Create the role on Deep Security Manager
    try:
        # Perform the search
        admin_roles_api = api.AdministratorRolesApi(api.ApiClient(configuration))
        new_role = admin_roles_api.create_administrator_role(run_reports_role, api_version)

        return "The role ID for the " + str(run_reports_role.name) + " role is " + str(new_role.id) + "."

    except api_exception as e:
        return "Exception: " + str(e)
JavaScript
/*
 * Creates a role with rights that are appropriate for reading computer properties and assigning policies to computers.
 * @param {object} api The api module.
 * @param {String} apiVersion The API version to use.
 * @return {Promise} A promise that contains the ID of the new role.
 */
exports.createRoleForComputerReports = function(api, apiVersion) {
  return new Promise((resolve, reject) => {= new api.Role();
    runReportsRole.name = "Computer Status and Properties";runReportsRole.allPolicies = false;= new api.ComputerRights();
    computerRights.canEditComputerProperties = true;

    const platformRights = new api.PlatformRights();
    platformRights.computerRights = computerRights;

    const rights = new api.Rights();
    rights.platformRights = platformRights;runReportsRole.rights = rights;= new api.AdministratorRolesApi();
    adminRolesApi
      .createAdministratorRole(runReportsRole, apiVersion)
      .then(newRole => {
        resolve(newRole.ID);
      })
      .catch(error => {
        reject(error);
      });
  });
};
Java
/*
 * Creates a role with rights that are appropriate for reading computer properties and assigning policies to computers.
 * @return An Integer that contains the ID of the new role.
 */
public static Integer createRoleForComputerReports() {= new Role();
	runReportsRole.setName("Computer Status and Properties");runReportsRole.setAllPolicies(false);= new ComputerRights();
	computerRights.setCanEditComputerProperties(true);

	PlatformRights platformRights = new PlatformRights();
	platformRights.setComputerRights(computerRights);
	
	Rights rights = new Rights();
	rights.setPlatformRights(platformRights);runReportsRole.setRights(rights);
	
	AdministratorRolesApi adminRolesApi = new AdministratorRolesApi();
	try {= adminRolesApi.createAdministratorRole(runReportsRole, "v1");
	} catch (ApiException e) {
		System.out.println(e.getMessage());
		e.printStackTrace();
	}
	return runReportsRole.getID();
}