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) {
	// Create and configure a Tenant object
	Tenant tenant = new Tenant();

	// Set module visibility
	List<ModulesVisibleEnum> modules = new ArrayList<ModulesVisibleEnum>();
	modules.add(ModulesVisibleEnum.ANTI_MALWARE);
	modules.add(ModulesVisibleEnum.FIREWALL);
	modules.add(ModulesVisibleEnum.INTRUSION_PREVENTION);

	// Administrator account
	Administrator admin = 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);

	// Add the tenant to the manager
	TenantsApi tenantsApi = 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");
// Add the key to Deep Security Manager
TenantsApi tenantsApi = 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>();
	// 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");
	// Add the key to Deep Security Manager
	TenantsApi tenantsApi = new TenantsApi();
	try {
		key = tenantsApi.generateTenantApiSecretKey(tenantID, key, "v1");

		// Configure the APIClient using the new key's secret
		ApiClient tenantClient = Configuration.getDefaultApiClient();
		ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) tenantClient.getAuthentication("DefaultAuthentication");
		DefaultAuthentication.setApiKey(key.getSecretKey());

		// Get the computers and find the states
		ComputersApi tnComputerApi = new ComputersApi(tenantClient);
		Computers computers;

		computers = tnComputerApi.listComputers(false, "v1");
		for (Computer computer : computers.getComputers()) {
			computerIPStates.put(computer.getID(), computer.getIntrusionPrevention().getState());
		}
		// Delete the tenant key
		ApiKeysApi tnApiKeysApi = 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) {
	// Create an API key for the tenant
	TenantsApi tenantsApi = new TenantsApi();
	ApiKey tenantKey = new ApiKey();
	tenantKey.setKeyName("Tenant Key");
	tenantKey.setRoleID(1);
	try {
		tenantKey = tenantsApi.generateTenantApiSecretKey(tenantID, tenantKey, "v1");

		// Configure an ApiClient object for the tenant
		ApiClient tenantClient = Configuration.getDefaultApiClient();
		ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) tenantClient.getAuthentication("DefaultAuthentication");
		DefaultAuthentication.setApiKey(tenantKey.getSecretKey());

		// Add the policy
		PoliciesApi tnPoliciesApi = new PoliciesApi(tenantClient);
		policy = tnPoliciesApi.createPolicy(policy, false, "v1");

		// Delete the tenant key
		ApiKeysApi tnApiKeysApi = 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() {
	// Key is tenant ID. Value is a list of computer rule IDs
	HashMap<Integer, HashMap<Integer, ArrayList<Integer>>> tenantMap = new HashMap<Integer, HashMap<Integer, ArrayList<Integer>>>();
	// Key is computer ID. Value is a list of rule IDs
	HashMap<Integer, ArrayList<Integer>> computerRules = new HashMap<Integer, ArrayList<Integer>>();

	//Obtain connection properties from local properties file
	ClassLoader classLoader = 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");

	//Configure the ApiClient
	ApiClient apiClient = Configuration.getDefaultApiClient();
	apiClient.setBasePath(primaryURL);
	ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) apiClient.getAuthentication("DefaultAuthentication");
	DefaultAuthentication.setApiKey(primarySecretKey);

	//Search for Active tenants 
	SearchCriteria searchCriteria = new SearchCriteria();
	searchCriteria.setFieldName("tenantState");
	searchCriteria.setChoiceValue("active");
	searchCriteria.setChoiceTest(SearchCriteria.ChoiceTestEnum.EQUAL);

	//Search filter
	SearchFilter searchFilter = new SearchFilter();
	searchFilter.setMaxItems(1);
	searchFilter.addSearchCriteriaItem(searchCriteria);
	
	TenantsApi tenantsApi = new TenantsApi();
	try {
		Tenants tenants = tenantsApi.searchTenants(searchFilter, "v1");
		
		//Iterate the tenants
		for (Tenant tenant : tenants.getTenants()) {
			System.out.println("Processing tenant " + tenant.getID());

			// For each tenant create an api key
			ApiKey tenantKey = new ApiKey();
			tenantKey.setKeyName("Temporary Key");
			tenantKey.setRoleID(1);
			tenantKey.setLocale(ApiKey.LocaleEnum.EN_US);
			tenantKey.setTimeZone("Asia/Tokyo");
			// Add the key to Deep Security Manager
			tenantKey = tenantsApi.generateTenantApiSecretKey(tenant.getID(), tenantKey, "v1");

			// Configure the ApiClient to use the tenant's secret key
			DefaultAuthentication.setApiKey(tenantKey.getSecretKey());

			// Create a ComputersApi object for the tenant
			ComputersApi tnComputersApi = new ComputersApi();
			// Iterate over the tenant computers
			Computers tenantComputers = 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);

			// Delete the tenant key
			ApiKeysApi tnApiKeysApi = new ApiKeysApi();
			tnApiKeysApi.deleteApiKey(tenantKey.getID(), "v1");
			tenantKey = null;
			System.out.println("Done tenant " + tenant.getID());

			//Configure the ApiClient to use the primary tenant's Secret Key
			DefaultAuthentication.setApiKey(primarySecretKey);
		}
	} catch (ApiException e) {
		e.printStackTrace();
	}
	return tenantMap;
}