| Status | ||||
|---|---|---|---|---|
|
In a VFC system, numerous entities exist containing credential-type data. The endpoints covered in this article allow changing the credentials programmatically. With the following functionality, a custom integrator application can be implemented to rotate passwords of the different entities from a common password vault solution. With this approach, common technical accounts' password leakage or sharing can be prevented. This article introduces how these credentials can be managed via the v1 REST API in the following sections. To get generic information about REST API usage, please visit the Use the REST API article.
| Table of Contents |
|---|
For the applications that manage credentials in the system, the following actions are required:
...
The Active Directory Synchronization Profile entities contain credential data to be able to connect to an LDAP server or an a Microsoft Entra (formerly Azure AD) tenant. The updateable properties are various and depend on the type of the AD Synchronization Profile entity.
...
The non-sensitive data change can be validated with the previous response, which contains the whole entity object with the new modified values. The sensitive information can be verified with the following request. Due to a Storage Target entities can have different types with different object properties, for password verification, the verified property name has to be passed with the checked plain password too.
...
The non-sensitive data change can be validated with the previous response, which contains the whole entity object with the new modified values. The sensitive information can be verified with the following request. Due to an Import Source entities can have different types with different object properties, for password verification, the verified property name has to be passed with the checked plain password too.
...
The server configurations are stored in two locations in the system: in the central database that allows to manage and review them the management of the values 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 locations. Basically, the values stored in the central database and the registry should not be The system was designed like this to minimize the actions performed by the recorder services: when multiple configuration values and/or multiple extension configurations should be changed, then all changes can be configured without influencing the services, and when everything is configured in the central database, then all recorded changes can be pushed to the server at the same time.
Basically, the values stored in the central database and the registry should not be different, but after a server installation or a manual registry change, there can be differences. Before configuring the server, the differences must be eliminated by using the configurationDifferences endpoint. When the central database value is chosen as the proper value, then one or more configuration tasks will be generated that indicates indicate the required changes in the registry .A server configuration change requires the and reread/restart actions for the affected services. When the server registry is chosen as the proper value, then the central database will be updated and no other action is required.
A server configuration change requires the following steps:
Step 1: Change the configurations in the central database. The changes don’t have a direct effect on the behavior of services after this change. Such changes are not considered as a difference between the registry and the central database, but a configuration task is generated instead, and the changes can be pushed to the servers' registry by executing this task.
...
Another difference between the server configuration-related endpoints and the other aforementioned introduced endpoints is password verification. As a result of the complex connection string format, there is no password verification action in these endpoints. The encrypted values can be retrieved by the client.
...
In the following sections, different use case examples demonstrate the usage of the server configuration-related endpoints.
Use case:
...
There are differences between the central database and the local registry
When there are differences, then a few configuration API endpoints will respond with an HTTP 409 Conflict status and error code PREREQUISITE_NOT_MET.
Step 1: change the configurationFirstly, the current value can be retrieved by the server hostname (“verbamr01") and URL encoded registry path (“%5CVerba%5CEmail%20Settings%5CTLSKeyPass") with the next requestRetrieve the list of the differences for a specific server
Request:
| Code Block |
|---|
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 encrypted with the following request:
Request:
| Code Block |
|---|
POST /verba/restapi/v1/encodePassword
new plain password |
Response:
| Code Block |
|---|
NEW ENCRYPTED PASSWORD |
This new value can be used to update the configuration in the local database.
| Code Block |
|---|
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 the central database and the local registry
Retrieve the list of the differences in the certain server.
Request:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationDifferences |
Response:
| Code Block |
|---|
{ "differences": [ { "path": "\\Verba\\Email configurationDifferences |
Response:
| Code Block |
|---|
{
"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
}
]
} |
Step 2: Resolve the differences
Based on the retrieved information, the differences must be resolved by items with a decision about specifying which data source contains the correct values. For the resolution, a list has to be sent with the correct data sources.
...
| Code Block |
|---|
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"
}
]
} "correctSource": "REGISTRY"
}
]
} |
Response:
| Code Block |
|---|
"differences": [] |
If there are no more differences in the configuration, then an empty list will be retrieved. During this step, when the central database value is chosen, then configuration tasks will be created for the server.
Use case: Individual server configuration modification
Step 1: Change the configuration
Firstly, the current value can be retrieved by the server hostname (“verbamr01") and URL encoded registry path (“%5CVerba%5CEmail%20Settings%5CTLSKeyPass") with the next request:
| Code Block |
|---|
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 encrypted with the following request:
Request:
| Code Block |
|---|
POST /verba/restapi/v1/encodePassword
new plain password |
Response:
| Code Block |
|---|
"differences": [] |
If there are no more differences in the configuration an empty list should be retrieved. In another case, the resolution must continue. During this step configuration tasks have been created for the server.
...
NEW ENCRYPTED PASSWORD |
This new value can be used to update the configuration in the local database.
| Code Block |
|---|
PUT https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configuration?settingPath=%5CVerba%5CEmail%20Settings%5CTLSKeyPass
NEW ENCRYPTED PASSWORD |
Step 2: Applying the configuration changes on the server
With the The following request can be used to list the created configuration tasks can be listed.:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationTasks |
If there is any item in the retrieved list is not empty, then those the tasks have to must be applied to that server. The actual application is done by the following requestthe server:
| Code Block |
|---|
POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr01/configurationTasks |
...
| Code Block |
|---|
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 , so 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 each server.
Request:
| Code Block |
|---|
GET https://VFC_MR_DOMAIN/verba/restapi/v1/configurationTasks |
...
| Code Block |
|---|
POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/verbamr02/configurationTasks |
Use case: Configure a
...
newly installed VFC server based on
...
the configuration of another existing server
In cloud-based solutions, to decrease the load of a server load , a possible solution is to start a new server with the same role to balance the load during peak times. This example shows a way how configuration management can be achieved for a similar use case.
In the example deployment, the verbamr01 server already exists and is configured. A new MR server has been started with a default configuration with the hostname verbamr02. With the recommended solution, the common configurations should be collected configured in a the configuration profile. In this case, firstly, the used configuration profile should be determined with the following request:
...
From this response, the configurationProfileId can be read out. That configuration profile can be set to the new server with the following requests. Firstly First, get the current server object from the new verbamr02.
...
That configuration list should be used as a template. After changing the values in the template, it can be sent for an import to the new server with the following request:
...
After the configuration changes, the generated configuration tasks should be applied on to the new server.
| Code Block |
|---|
POST https://VFC_MR_DOMAIN/verba/restapi/v1/servers/localhost/configurationTasks |