Methods for working with tenants

Using the Integration Server REST API, you can perform the following actions when working with tenants and tenant virtual machines:

• Get information about a tenant
• Get a list of tenants
• Get a list of tenant virtual machines
• Create a new tenant and its protection infrastructure, or register an existing tenant
• remove a tenant
• activate and deactivate a tenant
• register and unregister tenant virtual machines

The set of actions performed as a result of some REST API requests depends on the tenant type that you specify when adding the tenant information to the Integration Server database. Deployment and deletion of the tenant protection infrastructure using the Integration Server REST API is available for complete tenants. For a simple tenant, only report generation is automated.

Getting information about a tenant

Allows you to get information about the tenant from the Integration Server database.

Method:

GET /api/2.0/virtualization/tenants/{tenant ID}

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

In case of successful completion of the request, the REST API returns the following information about the tenant:

<tenant id="{ID}" created="{date and time}" updated="{date and time}">

<name>{name}</name>

<description>{description}</description>

<userData><![CDATA[{additional information}]]></userData>

<!-- Information in the vKsc section is available only for a complete tenant -->

<vKsc id="{ID}">

<user>

<name>{administrator}</name>

</user>

</vKsc>

<status>{status}</status>

<type>{tenant type}</type>

</tenant>

where:

• tenant id="{ID}" – tenant identifier in the Integration Server database.
• created="{date and time}" – date and time when the tenant was registered in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.
• updated="{date and time}" – date and time when the tenant data was updated in the Integration Server database, in YYYY-MM-DDThh:mm:ss format.
• {name} – tenant name specified when the tenant was created.
• {description} – tenant description.
• {additional information} – additional tenant information added to the Integration Server database.
• vKsc id="{ID}" – identifier assigned to the tenant's virtual Administration Server in Kaspersky Security Center.
• {administrator} – name of the administrator of the tenant's virtual Administration Server.
• {status} – current tenant status: Active or Inactive.
• {tenant type} – type of tenant: Complete or Simple.

Return codes:

• 200 (OK) – request completed successfully. The tenant information is returned in the response.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.

Getting a tenant list

Allows you to get a list of all tenants whose information is stored in the Integration Server database, as well as information about each tenant.

Method:

GET /api/2.0/virtualization/tenants

Return codes:

• 200 (OK) – request completed successfully. A list of information about all tenants is returned in the response.
• 403 (Forbidden) – access to the resource is denied.

Getting a list of tenant virtual machines

Allows you to get a list of all registered tenant virtual machines.

Method:

GET /api/2.0/virtualization/tenants/{tenant ID}/vms

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

If the request succeeds, the REST API returns a list of virtual machines and the following information about each tenant virtual machine:

<vm id="{ID in the database}" biosId={BIOS ID} created="{date and time}" updated="{date and time}">

<name>{name}</name>

<userData><![CDATA[{additional information}]]></userData>

</vm>

where:

• {ID in the database} – identifier assigned to the virtual machine in the Integration Server database.
• {BIOS ID} – virtual machine identifier (BIOS ID) in UUID format.
• created="{date and time}" – date and time when the virtual machine was registered in the Integration Server database in YYYY-MM-DDThh:mm:ss format.
• updated="{date and time}" – date and time when the virtual machine data was updated in the Integration Server database in YYYY-MM-DDThh:mm:ss format.
• {name} – virtual machine name.
• {additional information} – additional information about the virtual machine stored in the Integration Server database.

Return codes:

• 200 (OK) – request completed successfully. A list of the tenant virtual machines is returned in the response.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.

Creating a tenant

Depending on the tenant type that you specify when calling the REST API method, the following actions can be performed:

• For a complete tenant:
  • Add tenant data to the Integration Server database.
  • Create the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups).
  • Add information about the tenant's virtual Administration Server to the Integration Server database.
• For a simple tenant: add the tenant data to the Integration Server database.

Method:

POST /api/2.0/virtualization/tenants

The following parameters must be specified in the request body:

<tenant>

<name>{name}</name>

<description>{description}</description>

<userData><![CDATA[{additional information}]]></userData>

<preferredViisAddress>{IP address}</preferredViisAddress>

<type>{tenant type}</type>

<!-- Data in the vKsc section is specified only for a complete tenant -->

<vKsc>

<user>

<name>{administrator name}</name>

<password>{administrator password}</password>

</user>

</vKsc>

</tenant>

where:

• {name} – tenant name (required parameter).
• {description} – tenant description (optional parameter).
• {additional information} – additional tenant information (optional parameter).
• {IP address} – IP address of the Integration Server to which the Light Agents installed on tenant virtual machines will connect (optional parameter). The specified address is used by default when creating the Light Agent policy. If the parameter is not specified, the policy uses the Integration Server IP address from the request to REST API.
• {tenant type} – type of tenant: Complete or Simple (optional parameter).
• {administrator name} – name of the administrator account used to connect to the tenant's virtual Administration Server (required when creating a complete tenant). The account will be created automatically during the procedure.
• {administrator password} – Base64-encoded password for the administrator account (required when creating a complete tenant).

The request is executed asynchronously, REST API returns identifier of the CreateTenant task. Using the task, you can monitor the progress of the tenant creation procedure. When the task completes, the result field displays information about the tenant including the identifier of the created tenant, or an error message. In case of an error at any step of the procedure, all the changes are rolled back.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the CreateTenant task.
• 400 (Bad request) VIRMT_MandatoryParameterIsNotSpecified – one of the required parameters, for example, the tenant name, is not specified in the request body.
• 400 (Bad request) VIRMT_InvalidTenantType – an invalid tenant type is specified in the request body; the specified tenant type does not exist.
• 400 (Bad request) VIRMT_VKscCredentialsNotSpecified – the name or password of the administrator account of the virtual Kaspersky Security Center Administration Server is not specified (when creating a complete tenant).
• 400 (Bad request) VIRMT_InvalidViisAddressFormat – invalid format of the Integration Server IP address.
• 403 (Forbidden) – access to the resource is denied.

Possible error codes in the task:

• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.
• VIRMT_TenantGroupAlreadyExists – a folder whose name corresponds to the specified tenant name already exists in Kaspersky Security Center.
• VIRMT_TenantWithSpecifiedNameAlreadyExists – a tenant with the specified name already exists in the Integration Server database.
• VIRMT_PasswordNotComplyPolicy – failed to create an administrator account for Kaspersky Security Center virtual Administration Server: the specified password does not meet Kaspersky Security Center password requirements.
• VIRMT_UserWithSpecifiedNameAlreadyExists – failed to create an administrator account for Kaspersky Security Center virtual Administration Server: a user with the specified name already exists in Kaspersky Security Center.

Activating a tenant

Allows changing the tenant status to "Active".

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/activate

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.

Deactivating a tenant

Allows changing the tenant status to "Inactive".

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/deactivate

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The request is executed asynchronously, REST API returns identifier of the ChangeTenantActivation task. Using the task, you can monitor the progress of the procedure for changing the tenant status. When the task is done, the result field displays confirmation that the tenant status changed (true) or an error message.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the ChangeTenantActivation task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.

Registering tenant virtual machines

Allows you to add information about the tenant virtual machines to the Integration Server database.

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/register

where:

{tenant ID} – tenant identifier in the Integration Server database (required parameter).

The following parameters must be specified In the request body:

<vm biosId="{BIOS ID}">

<name>{name}</name>

<userData><![CDATA[{additional information}]]></userData>

</vm>

where:

• {BIOS ID} – unique virtual machine identifier (BIOS ID) (required parameter).
• {name} – virtual machine name (optional parameter).
• {additional information} – additional information about the virtual machine (optional parameter).

Return codes:

• 200 (OK) – request completed successfully (information about the virtual machine is added to the Integration Server database).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• 409 (Conflict) VIRMT_VmWithSpecifiedBiosIdAlreadyExists – virtual machine with the specified identifier is already registered in the Integration Server database.

Unregistering a virtual machine

Allows you to delete information about the tenant virtual machine from the Integration Server database.

Unregistration does not disable protection of the tenant virtual machine. You can disable protection of the virtual machine for a complete tenant by following all the steps of the procedure for removing virtual machines from the protected infrastructure.

Method:

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?biosId={ID}

or

POST /api/2.0/virtualization/tenants/{tenant ID}/vms/unregister?vmId={ID}

where:

• {tenant ID} – tenant identifier in the Integration Server database (required parameter).
• biosId={ID} – virtual machine identifier (BIOS ID) in UUID format (required parameter).
• vmId={ID} – identifier of the virtual machine in the Integration Server database, in the UUID format (required parameter).

Return codes:

• 200 (OK) – request completed successfully (information about the virtual machine is deleted from the Integration Server database).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• 404 (Not Found) VIRMT_VmWithSpecifiedIdNotFound – virtual machine with the specified identifier is not found in the Integration Server database.

Removing a tenant

Depending on the tenant type and specified parameters, lets you perform the following actions:

• For a complete tenant:
  • Delete information about the tenant and tenant virtual machines from the Integration Server database.
  • Delete the tenant protection infrastructure in Kaspersky Security Center (virtual Administration Server, account for connecting to it, structure of folders and administration groups, policies, tasks, and installation packages). If there are no other tenants, the Multitenancy KSV LA folder is also deleted.
  • Delete information about the tenant's virtual Administration Server from the Integration Server database.

  Calling the tenant removal method does not disable protection on tenant virtual machines. To disable protection, you need to perform all steps of the tenant removal procedure, including removal of Light Agent for Windows, Light Agent for Linux, and Kaspersky Security Center Network Agent from the virtual machines. To suspend protection of the virtual machine for a complete tenant, use the tenant deactivation method.

• For a simple tenant: remove the tenant from the Integration Server database.

Method:

DELETE /api/2.0/virtualization/tenants/{tenant ID}?removeTenantArtifacts={true|false}

where:

• {tenant ID} – tenant identifier in the Integration Server database (required parameter).
• removeTenantArtifacts={true|false} – optional parameter that indicates whether the tenant protection infrastructure must be removed when removing the tenant from the Integration Server database. Possible values:
  • true – when the tenant is removed, the following actions are performed:
    • Remove the tenant's virtual Administration Server.
    • Delete the administrator account of the tenant's virtual Administration Server.
    • Delete the Multitenancy KSV LA → <Tenant name> folder and its contents.
    • Delete the Multitenancy KSV LA folder if there are no other tenants.
  • false – the tenant is only deleted from the Integration Server database; the tenant protection infrastructure is not deleted.

The request is executed asynchronously, REST API returns identifier of the DeleteTenant task. You can use the task to monitor the progress of the tenant removal procedure. When the task completes, the result field displays information about the removed tenant or an error message.

In case of an error at any step of the procedure, all the changes are rolled back.

Return codes:

• 202 (Accepted) – the request is accepted for execution. The response returns the identifier of the DeleteTenant task.
• 403 (Forbidden) – access to the resource is denied.

Error codes in the task:

• VIRMT_TenantWithSpecifiedIdNotFound – a tenant with the specified identifier is not found in the Integration Server database.
• KSC_ServiceNotConfigured – Kaspersky Security Center connection settings are not specified.