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 can create the various roles that are suitable for the tasks that users perform, or that you perform using the API.
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 rolesRole
: Represents a role and provides access to role propertiesRights
classes: Several classes that represent access rights for Deep Security resources. For example,ComputerRights
defines rights for interacting with computers, andScheduledTaskRights
defines rights for interacting with scheduled tasks.
See also Obtain a role ID.
General steps
Use the following general steps to create or modify a role:
- 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.
- 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 data structure is useful for understanding how to configure the role's access rights:
- The
allComputers
andallPolicies
items control access to all computers and policies. If either arefalse
,computerIDs
andpolicyIDs
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.
The following example creates a Role object and sets the name:
run_reports_role = api.Role() run_reports_role.name = "Computer Status and Properties"
const runReportsRole = new api.Role(); runReportsRole.name = "Computer Status and Properties";
Role runReportsRole = new Role(); runReportsRole.setName("Computer Status and Properties");
Use a ComputerRights
object to specify access rights to computers, and then use the object to configure a PlatformRights
object. The PlatformRights
object corresponds with the platformRights
data item in the previous JSON code:
computer_rights = api.ComputerRights() computer_rights.can_edit_computer_properties = True platform_rights = api.PlatformRights() platform_rights.computer_rights = computer_rights
const computerRights = new api.ComputerRights(); computerRights.canEditComputerProperties = true; const platformRights = new api.PlatformRights(); platformRights.computerRights = computerRights;
ComputerRights computerRights = new ComputerRights(); computerRights.setCanEditComputerProperties(Boolean.FALSE); PlatformRights platformRights = new PlatformRights(); platformRights.setComputerRights(computerRights);
Add the platform rights to a Rights
object, and then add the Rights
object to the role.
rights = api.Rights() rights.platform_rights = platform_rights run_reports_role.rights = rights
const rights = new api.Rights(); rights.platformRights = platformRights; runReportsRole.rights = rights;
Rights rights = new Rights(); rights.setPlatformRights(platformRights); runReportsRole.setRights(rights);
Finally, create the role on Deep Security manager:
admin_roles_api = api.AdministratorRolesApi(api.ApiClient(configuration)) new_role = admin_roles_api.create_administrator_role(run_reports_role, api_version)
const adminRolesApi = new api.AdministratorRolesApi(); return adminRolesApi.createAdministratorRole(runReportsRole, apiVersion);
AdministratorRolesApi adminRolesApi = new AdministratorRolesApi(); runReportsRole = adminRolesApi.createAdministratorRole(runReportsRole, apiVersion);
Example: Create a role
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.
# 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 admin_roles_api = api.AdministratorRolesApi(api.ApiClient(configuration)) new_role = admin_roles_api.create_administrator_role(run_reports_role, api_version) return new_role.id
// Create the Role object const runReportsRole = new api.Role(); runReportsRole.name = "Computer Status and Properties"; // No need for access to policies runReportsRole.allPolicies = false; // Add rights to edit computer properties const computerRights = new api.ComputerRights(); computerRights.canEditComputerProperties = true; const platformRights = new api.PlatformRights(); platformRights.computerRights = computerRights; const rights = new api.Rights(); rights.platformRights = platformRights; // Add the rights to the role runReportsRole.rights = rights; // Create the role on Deep Security Manager const adminRolesApi = new api.AdministratorRolesApi(); adminRolesApi .createAdministratorRole(runReportsRole, apiVersion) .then(newRole => { resolve(newRole.ID); }) .catch(error => { reject(error); });
// Create the Role object Role runReportsRole = new Role(); runReportsRole.setName("Computer Status and Properties"); // No need for access to policies runReportsRole.setAllPolicies(Boolean.FALSE); // Add rights to edit computer properties ComputerRights computerRights = new ComputerRights(); computerRights.setCanEditComputerProperties(Boolean.FALSE); PlatformRights platformRights = new PlatformRights(); platformRights.setComputerRights(computerRights); Rights rights = new Rights(); rights.setPlatformRights(platformRights); // Add rights to the role runReportsRole.setRights(rights); // Create the role on Deep Security Manager AdministratorRolesApi adminRolesApi = new AdministratorRolesApi(); runReportsRole = adminRolesApi.createAdministratorRole(runReportsRole, apiVersion); return runReportsRole.getID();
Also see the Create an Administrator Role operation in the API Reference.