Control Access Using Roles | Trend Micro Service Central

Views:

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 Server & Workload Protection, your code can create 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.

Note

For background information about roles, see User Roles.

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 Server & Workload Protection resources. For example, ComputerRights defines rights for interacting with computers, and ScheduledTaskRights defines rights for interacting with scheduled tasks.

General steps

Use the following general steps to create or modify a role:

Procedure

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 Server & Workload Protection.

What to do next

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 Server & Workload Protection 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 and allPolicies items control access to all computers and policies. If either are false, computerIDs 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 Server & Workload Protection 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"

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

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

Finally, create the role on Server & Workload Protection:

admin_roles_api = api.AdministratorRolesApi(api.ApiClient(configuration))
new_role = admin_roles_api.create_administrator_role(run_reports_role, api_version)

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.

View source

# 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 Server & Workload Protection
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

Also see the Create an Administrator Role operation in the API Reference.