Contents
Using the Integration Server REST API in multi-tenancy scenarios
Interaction with the Integration Server REST API is based on requests and responses and is carried out over the HTTPS protocol using the multitenancy account.
Account parameters are passed as the following string {username}:{password} at every method call in the Authorization request header and are encoded with the Base64 method. Authentication of the Basic type is used.
The address of the request to the Integration Server REST API consists of the following parts:
https://{Integration Server address}:{Integration Server port}/{method}?{parameters}
where:
{Integration Server address}– IP address or fully qualified domain name (FQDN) of the Integration Server.{Integration Server port}– port for connecting to the Integration Server (port 7271 by default).{method}– method to call.{parameters}– method parameters, if any.
For processing requests that are time consuming and run asynchronously, tasks are used. The task is created as an intermediate query result.
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 the 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’s virtual machines
The set of actions performed as a result of some REST API requests depends on the tenant type attribute 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 the complete tenant type. For the simple tenant type, only report receiving function is automated.
Getting tenant information
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>
<!-- Data in the vKsc section is available only for a complete tenant type -->
<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 information about the tenant stored in the Integration Server database.vKsc id="{ID}"– identifier assigned to the tenant virtual Administration Server in Kaspersky Security Center.{administrator}– name of the administrator of the tenant virtual Administration Server.{status}– current tenant status:ActiveorInactive.{tenant type}– tenant type:CompleteorSimple.
Return codes:
200 (OK)– request completed successfully. The response returns the tenant information.403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– tenant with the specified identifier is not found in the Integration Server database.
Getting a list of tenants
Allows you to get a list of all tenants, information about which 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. The response returns information about all tenants as a list.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).
In case of successful completion of the request, 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. The response returns a list of the tenant virtual machines.403 (Forbidden)– access to the resource is denied.404 (Not Found) VIRMT_TenantWithSpecifiedIdNotFound– tenant with the specified identifier is not found in the Integration Server database.
Creating a new 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 type:
- 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).
- Create the policies for enabling and disabling protection of the virtual machines with Kaspersky Security for Virtualization 5.1 Light Agent installed in the Multitenancy KSV LA → <Tenant name> folder.
Policies for enabling and disabling protection are applied only if Kaspersky Security for Virtualization 5.1 Light Agent is installed in the tenant virtual infrastructure.
- Add information about the tenant virtual Administration Server to the Integration Server database.
- For a simple tenant type: 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 can be specified only for a complete tenant type -->
<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 information about the tenant (optional parameter).{IP address}– IP address of the Integration Server to which the Light Agents installed on the 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:CompleteorSimple(optional parameter).{administrator name}– name of the administrator account used to connect to the tenant virtual Administration Server (required when creating a complete tenant type). The account will be created automatically during the procedure.{administrator password}– password for the administrator account encoded by the Base64 method (required when creating a complete tenant type).
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 execution completes, the result field displays information about the tenant including the created tenant identifier, 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 is not specified in the request body, for example, the tenant name.400 (Bad request) VIRMT_InvalidTenantType– invalid tenant type is specified in the request body, the specified tenant type does not exist.400 (Bad request) VIRMT_VKscCredentialsNotSpecified– name or password of the administrator account of Kaspersky Security Center virtual Administration Server is not specified (when creating a complete tenant type).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– the folder with the name corresponding to the specified tenant name already exists in Kaspersky Security Center.VIRMT_TenantWithSpecifiedNameAlreadyExists– the 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 the tenant
Allows you to perform the following actions depending on the tenant type:
- For a complete tenant type:
- Change the tenant status to Active.
- Change the status of the policies for enabling protection of the virtual machines with Kaspersky Security for Virtualization 5.1 Light Agent installed.
Policies for enabling protection are applied only if Kaspersky Security for Virtualization 5.1 Light Agent is installed in the tenant virtual infrastructure. If there are no policies for enabling tenant protection, they will be automatically created.
- For a simple tenant type: only change 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 tenant status changing procedure. When the task execution completes, the result field displays confirmation that the tenant status is 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– the tenant with the specified identifier is not found in the Integration Server database.KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.
Deactivating the tenant
Allows you to perform the following actions depending on the tenant type:
- For a complete tenant type:
- Change the tenant status to Inactive.
- Change the status of the policies for disabling protection of the virtual machines with Kaspersky Security for Virtualization 5.1 Light Agent installed.
Policies for disabling protection are applied only if Kaspersky Security for Virtualization 5.1 Light Agent is installed in the tenant virtual infrastructure. If there are no policies for disabling tenant protection, they will be automatically created.
- For a simple tenant type: only change 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 tenant status changing procedure. When the task execution completes, the result field displays confirmation that the tenant status is 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– the 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– 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 complete tenant type 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}– virtual machine identifier 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– 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
Allows you to perform the following actions depending on the tenant type and the specified parameters:
- For a complete tenant type:
- Delete information about the tenant and the tenant virtual machines from the Integration Server database.
- Delete the tenant protection infrastructure deployed from 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 virtual Administration Server from the Integration Server database.
Calling the tenant removal method does not disable protection on the tenant virtual machines. To disable protection, 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 complete tenant type, use the tenant deactivation method.
- For a simple tenant type: 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 determines if to remove the tenant protection infrastructure 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 virtual Administration Server.
- Delete the administrator account of the tenant 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– only the tenant is 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. Using the task, you can monitor the progress of the tenant deletion procedure. When the task execution 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– the tenant with the specified identifier is not found in the Integration Server database.KSC_ServiceNotConfigured– Kaspersky Security Center connection settings are not specified.
Methods for working with reports
Using the Integration Server REST API, you can perform the following actions when working with tenant protection reports:
- Generate a report
- Upload a report
Report generation
Allows you to generate a report based on data saved to the Integration Server database, taking into account the specified report settings. You can specify the tenant on whose protection you want to generate a report, and the time interval for which you want to receive data.
In the header of the Accept request, pass the data output format: Accept:application/csv.
Method:
POST /api/2.0/virtualization/reports/tenants?tenantId={tenant ID}&from={date and time}&to={date and time}
where:
tenantId={tenant ID}– tenant identifier in the Integration Server database. If a tenant is specified, the report includes only information about the protection periods of this tenant’s virtual machines. If the tenant is not specified, the report will include data on all virtual machines that were protected during the specified period.from={date and time}– start date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value is not specified, the date of the earliest record in the Integration Server database is used.to={date and time}– end date and time of the reporting period in YYYY-MM-DDThh:mm:ss format. If the value not specified, the current date is used.
The request is executed asynchronously, REST API returns identifier of the CreateTenantReport task. Using the task, you can monitor the progress of the report generation procedure. When the task execution completes, the result field displays the report identifier or an error message.
Return codes:
202 (Accepted)– the request is accepted for execution. The response returns the identifier of the CreateTenantReport task.403 (Forbidden)– access to the resource is denied.404 (Not Found)– tenant with the specified identifier is not found in the Integration Server database.
Report upload
Allows you to upload a report generated before.
In the header of the Accept request, pass the data output format: Accept: application/csv.
The report can be uploaded in parts. You can specify the data range in the Range request header, for example:
Range: bytes=0-1023
In response to a request with this header, the REST API returns the 206 (Partial content) result and the first kilobyte of data. The response contains the Content-Range and Content-Length headers.
For example:
Content-Range: bytes=0-1023/123456
Content-Length: 1024
Method:
GET /api/2.0/virtualization/reports/tenants/{report ID}
where:
{report ID} – report identifier obtained as a result of successful completion of the CreateTenantReport task (required parameter).
Return codes:
200 (OK)– request completed successfully. The response returns the report data in the format specified in theAcceptheader.206 (Partial content)– request completed successfully. The response returns the part of the report specified by theRangeheading.403 (Forbidden)– access to the resource is denied.404 (Not Found)– report with the specified identifier is not found.415 (Unsupported Media Type)– unsupported format of the requested data (incorrect format was passed in theAcceptrequest header).
Methods for working with tasks
The tasks are used for processing requests that are time consuming and run asynchronously. Task statuses allow you to monitor the progress of actions specified in the request.
A task may have one of the following states:
- Created – task is created but not started.
- Starting – the task is in the process of starting.
- Running – the task is running. For a task in this state, the execution progress is displayed as a percent value.
- Completed – the task has been successfully completed. For a task in this state, the task execution result is displayed. The result contains task-specific data, for example, the new tenant identifier when the CreateTenant task is completed.
- Stopping – the task is being prepared for completion. If you stopped a task, it may be in this state before switching to the Canceled state.
- Failed – the task failed. For a task in this state, detailed error information is indicated.
- Canceled – the task is terminated by the user or the system. For a task in this state, detailed error information is indicated.
- Queued – the task has been queued and is waiting for execution to start.
By means of the Integration Server REST API, you can perform the following tasks:
- Get a list of tasks
- Get information about a specified task
- Cancel execution of a specified task
Getting task information
Allows you to get information about the task by its identifier.
Method:
GET /api/2.0/virtualization/tasks/{ID}
where:
{ID} – task identifier (required parameter).
In case of successful completion of the request, the REST API returns the following information about the task:
<task id="{ID}" created="{date and time}" stateChanged="{date and time}" changed="{date and time}">
<state>{state}</state>
<type>{type}</type>
<stage>{stage}</stage>
<progress>{execution progress}</progress>
<result>{result}</result>
<!-- If the task execution fails, an error message is displayed instead of the result.
<error>{error message}</error>
</task>
where:
{ID}– task ID.created="{date and time}"– task creation time in YYYY-MM-DDThh:mm:ss format.stateChanged="{date and time}"– time of the task state change in YYYY-MM-DDThh:mm:ss format.changed="{date and time}"– task change time in YYYY-MM-DDThh:mm:ss format.{state}– task state.{type}– task type. For example:CreateTenant– a task that is used in the tenant creation procedure.ChangeTenantActivation– a task that is used in the tenant activation and deactivation procedures.DeleteTenant– a task that is used in the tenant deletion procedure.CreateTenantReport– a task that is used in the tenant protection report generation procedure.
{name}– task name.{stage}– task execution stage.{execution progress}– the progress of task execution indicated as a percentage.{result}– task execution result, for example, information about the created tenant or report identifier.{error message}– if an error occurs during task execution, an error message is displayed.
Return codes:
200 (OK)– request completed successfully.403 (Forbidden)– access to the resource is denied.404 (Not Found)– task with the specified identifier is not found in the Integration Server database.
Getting a list of tasks
Allows you to get a list of all existing tasks and information about each task in the list.
Method:
GET /api/2.0/virtualization/tasks?createdFrom={date and time}&state={status}&type={type}
where:
createdFrom={date and time}– date and time in YYYY-MM-DDThh:mm:ss format (optional parameter). If the parameter is specified, the list displays the tasks that were created not earlier than the specified date and time.state={state}– task state (optional parameter). If the parameter is specified, the list displays only the tasks with the specified state.type={type}– task type (optional parameter). If the parameter is specified, the list displays only the tasks of the specified type.
Return codes:
200 (OK)– request completed successfully. The response returns a list of tasks.403 (Forbidden)– access to the resource is denied.
Canceling a task
Allows you to stop running tasks. Some tasks cannot be completed immediately. In this case, the 202 (Accepted) code is returned and the task state changes to Stopping.
Method:
POST /api/2.0/virtualization/tasks/{ID}/cancel
where:
{ID} – task identifier (required parameter).
Return codes:
200 (OK)– request completed successfully (the task was canceled).202 (Accepted)– request is accepted for execution (the task state changes to Stopping).403 (Forbidden)– access to the resource is denied.404 (Not Found)– task with the specified identifier is not found.405 (Method Not Allowed)– for child tasks: you can cancel a child task only if you cancel the parent task.409 (Conflict)– the task is already in one of the following states: Cancelled, Failed, Stopped.