Authenticate and Interact 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.

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.The process to create an API key for a tenant is similar to that for creating an API key for the primary tenant. (See Create an API Key Using Code.)

  1. Create an ApiKey object and configure the properties.
  2. Create a TenantsApi object and use it to create the API key on the tenant.
Python

View source

# Create an API key
key = api.ApiKey()
key.key_name = "Temporary Key"
key.role_id = 1
key.locale = "en-US"
key.time_zone = "Asia/Tokyo"

# Generate the secret key for the tenant
tenants_api = deepsecurity.TenantsApi()
generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)
JavaScript

View source

// Creates an API key
const createKey = () => {
  // ApiKey properties
  const key = new api.ApiKey();
  key.keyName = "Temporary Key";
  key.roleID = 1;
  key.locale = api.ApiKey.LocaleEnum["en-US"];
  key.timeZone = "Asia/Tokyo";
  const tenantsApi = new api.TenantsApi();
  return tenantsApi.generateTenantApiSecretKey(tenantID, key, apiVersion);
};
Java

View source

// 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();
}

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.

Python
tenant_client = api.ApiClient()
tenant_client.configuration = api.Configuration()
tenant_client.configuration.api_key['api-secret-key'] = tenant_key.secret_key
JavaScript
// Configure the ApiClient for connecting to the tenant
const tenantClient = api.ApiClient.instance;
const defaultAuthentication = tenantClient.authentications["DefaultAuthentication"];
defaultAuthentication.apiKey = tenantKey.secretKey;
Java
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 demonstrates how to authenticate and interact with a tenant:

  1. Creates an API key on the tenant.
  2. Configures ApiClient to use the tenant API key.
  3. Obtains the Intrusion Prevention information from each computer that the tenant protects.
  4. Configures ApiClient to use the API key of the primary tenant.
Tenant keys expire 6 hours after creation by default.
Python

View source

primary_key = configuration.api_key['api-secret-key']

# Create an API key
key = api.ApiKey()
key.key_name = "Temporary API Key"
key.role_id = 1
key.locale = "en-US"
key.time_zone = "Asia/Tokyo"

try:
    # Check that the tenant is in the 'active' state
    import time
    while True:
        state = api.TenantsApi(api.ApiClient(configuration)).describe_tenant(tenant_id, api_version).tenant_state
        if state == 'active':
            break
        time.sleep(5)

    # Generate the secret key for the tenant
    tenants_api = api.TenantsApi(api.ApiClient(configuration))
    generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)

    # Add the secret key to the configuration
    configuration.api_key['api-secret-key'] = generated_key.secret_key

    # Include Intrusion Prevention information in the returned Computer objects
    expand = api.Expand(api.Expand.intrusion_prevention)

    # Get a list of tenant computers
    computers_api = api.ComputersApi(api.ApiClient(configuration))
    computers_list = computers_api.list_computers(api_version, expand=expand.list(), overrides=False)

    # Find the Intrusion Prevention state for each computer
    computer_ip_states = {}
    for computer in computers_list.computers:
        computer_ip_states[computer.id] = computer.intrusion_prevention.state

    # Delete an ApiKey from the tenant
    api_keys_api = api.APIKeysApi(api.ApiClient(configuration))
    api_keys_api.delete_api_key(generated_key.id, api_version)

    # Reset the API key to the primary key
    configuration.api_key['api-secret-key'] = primary_key

    return computer_ip_states

except api_exception as e:
    return "Exception: " + str(e)
JavaScript

View source

const computerIPStates = [];

// Creates an API key
const createKey = () => {
  // ApiKey properties
  const key = new api.ApiKey();
  key.keyName = "Temporary Key";
  key.roleID = 1;
  key.locale = api.ApiKey.LocaleEnum["en-US"];
  key.timeZone = "Asia/Tokyo";

  const tenantsApi = new api.TenantsApi();
  return tenantsApi.generateTenantApiSecretKey(tenantID, key, apiVersion);
};

// Gets a list of tenant computers
const getComputers = apiClient => {
  const computersApi = new api.ComputersApi(apiClient);
  return computersApi.listComputers(apiVersion, { overrides: "false" });
};

// Deletes an ApiKey from a tenant
const deleteKey = (apiClient, keyID) => {
  const apiKeysApi = new api.APIKeysApi();
  apiKeysApi.deleteApiKey(keyID, apiVersion).catch(error => {
    console.log(error);
  });
};

// Configure the ApiClient for connecting to the tenant
const tenantClient = api.ApiClient.instance;
const defaultAuthentication = tenantClient.authentications["DefaultAuthentication"];
let tenantKey;

createKey()
  .then(newKey => {
    tenantKey = newKey;
    defaultAuthentication.apiKey = newKey.secretKey;
    return getComputers(tenantClient);
  })
  .then(computers => {
    // Get the state of Intrusion Prevention module for each computer
    for (let i = 0; i < computers.computers.length; i++) {
      computerIPStates[i] = {
        ID: computers.computers[i].ID,
        IpState: computers.computers[i].intrusionPrevention.state
      };
    }
    deleteKey(tenantClient, tenantKey.ID);
    resolve(computerIPStates);
  })
  .catch(error => {
    reject(error);
  });
Java

View source

Map<Integer, IntrusionPreventionComputerExtension.StateEnum> computerIPStates = new HashMap<>();

// Create the key object
ApiKey key = new ApiKey();
key.setKeyName("Temporary Key");
key.setRoleID(roleID);
key.setLocale(ApiKey.LocaleEnum.EN_US);
key.setTimeZone("Asia/Tokyo");

// Add the key to Deep Security Manager
TenantsApi tenantsApi = new TenantsApi();
key = tenantsApi.generateTenantApiSecretKey(tenantID, key, apiVersion);

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

// Include Intrusion Prevention information in the returned Computer objects
Expand expand = new Expand(Expand.OptionsEnum.INTRUSION_PREVENTION);

// Get the computers and find the states
ComputersApi tnComputerApi = new ComputersApi(tenantClient);
Computers computers;
computers = tnComputerApi.listComputers(expand.list(), Boolean.FALSE, apiVersion);

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(), apiVersion);

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.

Python

View source

# Generate the secret key for the tenant
tenants_api = api.TenantsApi(api.ApiClient(configuration))
generated_key = tenants_api.generate_tenant_api_secret_key(tenant_id, key, api_version)

# Add the secret key to the configuration
configuration.api_key['api-secret-key'] = generated_key.secret_key

# Add the policy
tenant_policies_api = api.PoliciesApi(api.ApiClient(configuration))
tenant_client_with_policy = tenant_policies_api.create_policy(policy, api_version, overrides=False)

# Delete an ApiKey from the tenant
api_keys_api = api.APIKeysApi(api.ApiClient(configuration))
api_keys_api.delete_api_key(generated_key.id, api_version)

# Reset the API key to the primary key
configuration.api_key['api-secret-key'] = primary_key

return tenant_client_with_policy
JavaScript

View source

// Creates an API key
const createKey = () => {
  // ApiKey properties
  const key = new api.ApiKey();
  key.keyName = "Test Key";
  key.roleID = 1;
  key.locale = api.ApiKey.LocaleEnum["en-US"];
  key.timeZone = "Asia/Tokyo";
  const tenantsApi = new api.TenantsApi();
  return tenantsApi.generateTenantApiSecretKey(tenantID, key, apiVersion);
};

// Adds a policy to the tenant
const addPolicy = apiClient => {
  const policiesApi = new api.PoliciesApi(apiClient);
  return policiesApi.createPolicy(policy, apiVersion, <span class="x x-first">{ overrides</span><span class="pl-k x">:</span> <span class="pl-c1">false</span><span class="x x-first x-last"> }</span>);
};

// Deletes an ApiKey from a tenant
const deleteKey = (apiClient, keyID) => {
  const apiKeysApi = new api.APIKeysApi();
  apiKeysApi.deleteApiKey(keyID, apiVersion).catch(error => {
    console.log(error);
  });
};

// ApiClient for connecting to the tenant
const tenantClient = api.ApiClient.instance;
const DefaultAuthentication = tenantClient.authentications["DefaultAuthentication"];
let tenantKey;
createKey()
  .then(newKey => {
    tenantKey = newKey;
    DefaultAuthentication.apiKey = newKey.secretKey;
    return addPolicy(tenantClient);
  })
  .then(newPolicy => {
    deleteKey(tenantClient, tenantKey.ID);
    resolve(newPolicy);
  })
  .catch(error => {
    reject(error);
  });
Java

View source

// Create an API key for the tenant
tenantKey = tenantsApi.generateTenantApiSecretKey(tenantID, tenantKey, apiVersion);

// Create an ApiClient object for the tenant
ApiClient tenantClient = Configuration.getDefaultApiClient();
tenantClient.setBasePath("https://localhost:4119/api");
ApiKeyAuth defaultAuthentication = (ApiKeyAuth)tenantClient.getAuthentication("DefaultAuthentication");
defaultAuthentication.setApiKey(tenantKey.getSecretKey());

// Add the policy
PoliciesApi tnPoliciesApi = new PoliciesApi(tenantClient);
policy = tnPoliciesApi.createPolicy(policy, Boolean.FALSE, apiVersion);

// Delete the tenant key
ApiKeysApi tnApiKeysApi = new ApiKeysApi(tenantClient);
tnApiKeysApi.deleteApiKey(tenantKey.getID(), apiVersion);