Create and Manage Tenants

The Deep Security API enables you to programmatically create, modify, and delete tenants on Deep Security Manager.

For more information about multi-tenant deployments, see the Deep Security Help Center.

Enable multi-tenancy

Before you can interact with tenants, you need to enable multi-tenancy on Deep Security Manager. You must use the UI to enable multi-tenancy.

Create and configure a tenant

Create a tenant and configure the runtime aspects of the account:

  • Which security modules are visible to them in Deep Security Manager
  • Which database server to use (if Deep Security Manager uses multiple databases)
  • Locale and location details

To create a tenant using a client library, you create a Tenant object, set the property values, and then use a TenantsApi object to create the tenant on Deep Security Manager. One of the Tenant object properties is an Administrator object with, at a minimum, the user name, password, and email address defined. When the tenant is created, the administrator account is created on the tenant, and you use the account’s credentials to log into the tenant.

When creating a tenant, the following administrator account properties are persisted: the user name, password, time format, timezone, role, and all boolean properties. All other properties are ignored.

Example: Create a tenant

/*
 * Creates a tenant on the primary Deep Security Manager
 * @param activationCode The activation code for the tenant if required.
 * @param admin An Administrator object that contains credentials.
 * @return The new tenant.
 */
public static Tenant createTenant(String accountName) {= new Tenant();List<ModulesVisibleEnum> modules = new ArrayList<ModulesVisibleEnum>();
	modules.add(ModulesVisibleEnum.ANTI_MALWARE);
	modules.add(ModulesVisibleEnum.FIREWALL);
	modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION);= new Administrator();
	admin.setUsername("MasterAdmin");
	admin.setPassword("P@55word");
	admin.setEmailAddress("bad@email.com");

	tenant.setName(accountName);
	tenant.setLocale(Tenant.LocaleEnum.EN_US);
	tenant.setDescription("Test tenant.");
	tenant.setAdministrator(admin);
	tenant.setModulesVisible(modules);= new TenantsApi();
	try {
		tenant = tenantsApi.createTenant(tenant, true, false, true, "v1");
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return tenant;
}

For information about authenticating API calls, see Authenticate with Deep Security Manager.

Authenticate with a tenant

To authenticate with a tenant you need to create a tenant API key and use the key to configure an ApiClient object.

Example: Create a tenant API key

Create an API key for a tenant so that you can use the API to automate tasks on the tenant. You use the primary manager to create the tenant key, so to perform the operation you authenticate with the primary manager. When the tenant key is created, it appears in the Deep Security Manager of the tenant account.

If you do not set the roleID for the key, the key is provided full access.

// Create the key object
ApiKey key = new ApiKey();
key.setKeyName("Temporary Key");
key.setRoleID(1);
key.setLocale(ApiKey.LocaleEnum.EN_US);
key.setTimeZone("Asia/Tokyo");= new TenantsApi();
try {
	key = tenantsApi.generateTenantApiSecretKey(tenantID, key, "v1");
} catch (ApiException e) {
	e.printStackTrace();
}

Example: Configure an ApiClient object for a tenant

Configure the ApiClient to use the secret key of the tenant’s API key and then send requests to the Deep Security Manager of the tenant. From the secret key, the manager determines which tenant you are targeting.

After you configure the ApiClient, all calls are authenticated using the tenant’s API key and the calls target the associated tenant. After you are done interacting with the tenant and you want to make calls to the primary tenant, configure the ApiClient to use an API key for the primary tenant and then make the calls.

ApiClient tenantClient = Configuration.getDefaultApiClient();
ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) tenantClient.getAuthentication("DefaultAuthentication");
DefaultAuthentication.setApiKey(tenantKey.getSecretKey());

Example: Obtain Intrusion Prevention states of tenant computers

The following example creates a tenant API key and uses the key to obtain Intrusion Prevention states of the tenant computers.

Tenant keys expire 6 hours after creation by default.

/*
 * Retrieves the state of the intrusion prevention module for a tenant's
 * computers
 * @param tenantID The ID of the tenant.
 * @return A HashMap that uses the computer ID as the key and the intrusion
 * prevention state as the value.
 */
public static HashMap<Integer, IntrusionPreventionComputerExtension.StateEnum> getIPStatesForTenant(Integer tenantID) {

	HashMap<Integer, IntrusionPreventionComputerExtension.StateEnum> computerIPStates = new HashMap<Integer, IntrusionPreventionComputerExtension.StateEnum>();= new ApiKey();
	key.setKeyName("Temporary Key");
	key.setRoleID(1);
	key.setLocale(ApiKey.LocaleEnum.EN_US);
	key.setTimeZone("Asia/Tokyo");= new TenantsApi();
	try {
		key = tenantsApi.generateTenantApiSecretKey(tenantID, key, "v1");key's secret
		ApiClient tenantClient = Configuration.getDefaultApiClient();
		ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) tenantClient.getAuthentication("DefaultAuthentication");
		DefaultAuthentication.setApiKey(key.getSecretKey());= new ComputersApi(tenantClient);
		Computers computers;

		computers = tnComputerApi.listComputers(false, "v1");
		for (Computer computer : computers.getComputers()) {
			computerIPStates.put(computer.getID(), computer.getIntrusionPrevention().getState());
		}= new ApiKeysApi(tenantClient);
		tnApiKeysApi.deleteApiKey(key.getID(), "v1");
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return computerIPStates;
}

Example: configure policies for tenants

Create and configure policies for tenants in the same way that you do for the primary Deep Security Manager, except that you use a tenant API key for authentication. The following example creates an API key for a tenant and then uses the key to configure an ApiClient object. The client interacts with the tenant’s Deep Security Manager.

For more information about using the API to work with policies, see Create and Configure Policies.

/*
 * Adds a policy to a tenant
 * @param dsmClient An ApiClient object for the primary manager.
 * @param policy The Policy to add to the tenant.
 * @param tenandID The ID of the tenant.
 * @return The created policy.
 */
public static Policy addTenantPolicy(Policy policy, Integer tenantID) {= new TenantsApi();
	ApiKey tenantKey = new ApiKey();
	tenantKey.setKeyName("Tenant Key");
	tenantKey.setRoleID(1);
	try {
		tenantKey = tenantsApi.generateTenantApiSecretKey(tenantID, tenantKey, "v1");= Configuration.getDefaultApiClient();
		ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) tenantClient.getAuthentication("DefaultAuthentication");
		DefaultAuthentication.setApiKey(tenantKey.getSecretKey());= new PoliciesApi(tenantClient);
		policy = tnPoliciesApi.createPolicy(policy, false, "v1");= new ApiKeysApi(tenantClient);
		tnApiKeysApi.deleteApiKey(tenantKey.getID(), "v1");

	} catch (ApiException e) {
		e.printStackTrace();
	}
	return policy;
}

Iterate over tenants

Iterate over your active tenants and their computers when you need to perform an operation on all computers. For example, perform the following steps to create a report that details the protection status of all computers of active tenants:

  1. Search for active tenants. Create a search filter and then use a TenantsApi object to obtain a list of active Tenant objects. You use an API key of the primary Deep Security Manager to authenticate this request.
  2. For each tenant, create (or retrieve from storage) an API key.
  3. For each tenant, retrieve all computers. Use a ComputersApi object, and authenticate using the tenant key.
  4. Perform operations on each computer.

Example: Obtain intrusion prevention rules for all computers of active tenants

The following example iterates over the computers of each active tenant to obtain a list of Intrusion Prevention rules that are applied to each computer.

/*
 * Retrieves the Intrusion Prevention rules that are applied to all computers of
 * all tenants.
 * @return A HashMap object that uses the tenant ID as the key, and a HashMap of
 * rules that are applied to the computers.
 */

public static HashMap<Integer, HashMap<Integer, ArrayList<Integer>>> getTenantRules() {ID. Value is a list of computer rule IDs
	HashMap<Integer, HashMap<Integer, ArrayList<Integer>>> tenantMap = new HashMap<Integer, HashMap<Integer, ArrayList<Integer>>>();ID. Value is a list of rule IDs
	HashMap<Integer, ArrayList<Integer>> computerRules = new HashMap<Integer, ArrayList<Integer>>();= Thread.currentThread().getContextClassLoader();
	InputStream input = classLoader.getResourceAsStream("com/trendmicro/deepsecurity/docs/Resources/example.properties");
	Properties properties = new Properties();
	try {
		properties.load(input);
	} catch (IOException e) {
		e.printStackTrace();
	}
	String primarySecretKey = properties.getProperty("secretkey");
	String primaryURL = properties.getProperty("url");= Configuration.getDefaultApiClient();
	apiClient.setBasePath(primaryURL);
	ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) apiClient.getAuthentication("DefaultAuthentication");
	DefaultAuthentication.setApiKey(primarySecretKey);= new SearchCriteria();
	searchCriteria.setFieldName("tenantState");
	searchCriteria.setChoiceValue("active");
	searchCriteria.setChoiceTest(SearchCriteria.ChoiceTestEnum.EQUAL);= new SearchFilter();
	searchFilter.setMaxItems(1);
	searchFilter.addSearchCriteriaItem(searchCriteria);
	
	TenantsApi tenantsApi = new TenantsApi();
	try {
		Tenants tenants = tenantsApi.searchTenants(searchFilter, "v1");(Tenant tenant : tenants.getTenants()) {
			System.out.println("Processing tenant " + tenant.getID());= new ApiKey();
			tenantKey.setKeyName("Temporary Key");
			tenantKey.setRoleID(1);
			tenantKey.setLocale(ApiKey.LocaleEnum.EN_US);
			tenantKey.setTimeZone("Asia/Tokyo");= tenantsApi.generateTenantApiSecretKey(tenant.getID(), tenantKey, "v1");tenant's secret key
			DefaultAuthentication.setApiKey(tenantKey.getSecretKey());= new ComputersApi();= tnComputersApi.listComputers(false, "v1");
			for (Computer tenantComputer : tenantComputers.getComputers()) {
				IntrusionPreventionComputerExtension intrusionPeventionComputerExtension = tenantComputer.getIntrusionPrevention();
				ArrayList<Integer> ruleIds = (ArrayList<Integer>) intrusionPeventionComputerExtension.getRuleIDs();
				computerRules.put(tenantComputer.getID(), ruleIds);
			}
			tenantMap.put(tenant.getID(), computerRules);= new ApiKeysApi();
			tnApiKeysApi.deleteApiKey(tenantKey.getID(), "v1");
			tenantKey = null;
			System.out.println("Done tenant " + tenant.getID());tenant's Secret Key
			DefaultAuthentication.setApiKey(primarySecretKey);
		}
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return tenantMap;
}