Page Comparison

In a VFC system numerous entities exist containing credential type data. The endpoints covered in this articles allow to change the credentials programmatically. With the following functionality custom integrator application can be implemented to rotate passwords of the different entities from a common password vault solution. With this approach the common technical account password leakage or sharing can be prevented. This article introduces how these credentials can be managed via the v1 REST API.

...

The server configurations are stored in two location in the system: in a central database that allows to manage and review them via the user interface; and in every server’s registry that allows the local services to read them. The current configuration values can be retrieved from both location. A server configuration change in both approach require the following steps:

...

The following sections different use case examples demonstrates the usage of the server configuration related endpoints.

Use case: Individual server configuration modification

Due to the server configurations are stored in two different location: central database and registry valuesStep 1: change the configuration

Firstly, the current configuration values can be retrieved from both location.value can be retrieved by the server hostname (“verbamr01") and URL encoded registry path (“%5CVerba%5CEmail%20Settings%5CTLSKeyPass") with the next request:

GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass&source=REGISTRY

If the value should be encrypted, like in this case, the new value should be encrypt with the following request:

Request:

POST /verba/restapi/v1/encodePassword

new plain password

Response:

NEW ENCRYPTED PASSWORD

This new value can be used to update the the configuration in the local database.

PUT https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass

NEW ENCRYPTED PASSWORD

Step 2: resolve the difference between central database and local registry

Retrieve the list of the differences in the certain server.

Request:

GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationDifferences

Response:

{
  "differences": [
    {
      "path": "\\Verba\\Email Settings\\TLSKeyPass",
      "valueRegistry": "old encrypted password",
      "valueDb": "NEW ENCRYPTED PASSWORD",
      "serverCustom": false
    },
    {
      "path": "\\Verba\\Email Settings\\TLSCert",
      "valueRegistry": "foo",
      "valueDb": "",
      "serverCustom": false
    }
  ]
}

Based on the retrieved information the differences must be resolved by items with a decision about which data source contains the correct values. For the resolution a list has to be sent with the correct data sources.

Request:

POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationDifferences
Content-Type: application/json

{
  "resolutions": [
    {
      "path": "\\Verba\\Email Settings\\TLSKeyPass",
      "correctSource": "DATABASE"
    },
    {
      "path": "\\Verba\\Email Settings\\TLSCert",
      "correctSource": "REGISTRY"
    }
  ]
}

Response:

"differences": []

If there is no more differences in the configuration an empty list should retrieved. Other case the resolution must continue. During this step configuration tasks have been created for the server.

Step 3: applying the configuration changes on the server

With the following request the created configuration tasks can be listed.

GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationTasks

If there is any item in the retrieved list, then those tasks have to be applied on that server. The actual application is done by the following request:

POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationTasks

Use case: Multiple server configuration modification with configuration profile

The steps and the basic strategy is the same as the previous use case example. The only main difference is that while in the last example on configuration was only associated with one server, then in this example multiple servers can be affected the by the change.

The current configuration profile values can be retrieved similar to the server configuration values by the registry path, but here the ID of the configuration profile is needed:

GET https://VFC_MR_DOMAIN/verba/restapi/v1/configurationProfiles/2/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass

If the value should be encrypted then the encrypted value must be prepared. The configuration change can be done with the next request:

PUT https://VFC_MR_DOMAIN/verba/restapi/v1/configurationProfiles/1/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass

NEW ENCRYPTED PASSWORD

After one change every server is affected that uses the changed configuration profile. Due to that the necessary configuration tasks have been created by the system for every related server. In the case of configuration profile there is no need to resolve differences. The following request retrieves the list of the created configuration tasks for every server.

Request:

GET https://VFC_MR_DOMAIN/verba/restapi/v1/configurationTasks

Response:

{
  "list": [
      {
        "action": "send_config",
        "service": "",
        "server": "verbamr01",
        "configurationChanges": [
          {
            "name": "\\Verba\\Email Settings\\TLSKeyPass",
            "value": "*********"
          }
        ]
      },
      {
        "action": "restart",
        "service": "VerbaWebApp",
        "server": "verbamr01",
        "configurationChanges": null
      },
      {
        "action": "send_config",
        "service": "",
        "server": "verbamr02",
        "configurationChanges": [
          {
            "name": "\\Verba\\Email Settings\\TLSKeyPass",
            "value": "*********"
          }
        ]
      },
      {
        "action": "restart",
        "service": "VerbaWebApp",
        "server": "verbamr02",
        "configurationChanges": null
      }
  ]
}

From the retrieved list of tasks a unique server host name set should be collected (multiple tasks can exists for one server). Based on that unique set the configuration task application must be executed with the following requests on every affected server:

POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationTasks

POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr02/configurationTasks

Use case: