Page Comparison

,

In a VFC system numerous entities exist containing credential-type data. The endpoints covered in this articles article allow to change 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 the , common technical account 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.

The For the applications that manages manage credentials in the system the following actions are required:

• Listing entities: to identify the existing entities. The sensitive passwords are stored in an encrypted format in the database. With the API neither the plain nor the encrypted password cannot be retrieved.

• Retrieve one entity by ID: to fetch the latest public values of an entity. Similar to the listing action the sensitive properties cannot be retrieved.

• Modify properties of an entity: to actually change the credentials such as the password. Not every property of an entity can be updated. The allowed properties are listed in the REST API documentation site for every update endpoint. The modification action can be achieved with the PATCH HTTP method. This method allows the client to send only the changed properties to the server.

• Verify the password change: to send the known plain password to the system and retrieve a true or false value based on the sent plain password matches matching with the currently stored value. After a certain number of failed verification attempts the system blocks the API user from further requests to prevent password guessing.

The following sections cover descriptions and examples of how the credential management can be achieved for the different entities.

User credentials

The non-AD synchronized user entities have an updateable password field that can be modified with the API. Note: the login name is not modifiable. The new password must match with the configured password criteria i.e.: complexity or password history.

The following example shows how to change a user’s password with a PATCH method. The password has to be in plain format. The effect of the change take takes place immediately after a successful PATCH update request.

PATCH https://VFC_MR_DOMAIN/verba/restapi/v1/users/16
Content-Type: application/json

{
  "password": "new plain password"
}

After the change, the modification can be verified with the following request. For the user password verification, only the plain password is needed to pass in the body of the POST request.

...

The following example shows how to change the login name and the password for an LDAP server in the same request. The password has to be in plain format. The effect of the change take takes place immediately after a successful PATCH update request.

...

{
  "host": "ldap host",
  "port": 1234,
  "userName": "john.doe",
  "id": "13F72189-2EEB-425F-885B-7D1BBA83DDEB",
  "description": "LDAP AD Synchronization Profile description",
  "enabled": true,
  "type": "ldap"
}

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 AD Synchronization Profile entities can have different types with different object properties, for the password verification, the verified property name has to be passed too with the checked plain password too.

POST https://VFC_MR_DOMAIN/verba/restapi/v1/adSyncProfiles/13F72189-2EEB-425F-885B-7D1BBA83DDEB/password/verify
Content-Type: application/json
Accept: application/json

{
  "property": "ldapPassword",
  "value": "new plain password"
}

...

The following example shows how to change credentials for an Amazon S3 storage target in the same request. The password has to be in plain format. The effect of the change take takes place immediately after a successful PATCH update request.

...

{
  "bucket": "bucket name",
  "region": "region",
  "objectLockEnabled": true,
  "objectLockMode": "compliance",
  "accessKeyId": "amazons3_storage_keyid",
  "id": 11,
  "name": "Amazon S3",
  "type": "amazon_s3"
}

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 the password verification the verified property name has to be passed too with the checked plain password too.

POST https://VFC_MR_DOMAIN/verba/restapi/v1/storageTargets/11/password/verify
Content-Type: application/json
Accept: application/json

{
  "property": "secretAccessKey",
  "value": "new plain password"
}

...

Similar to Storage Targets the different Import Source types have different object schema representations in the REST API. The modifiable properties are depend on the specific type.

The following example shows how to change credentials for an a Zoom Phones import source in one request. The password has to be in plain format. The effect of the change take takes place immediately after a successful PATCH update request.

...

{
  "authType": "jwt",
  "apiKey": "zoom_api_key",
  "forwardProxyAddress": "proxy address",
  "forwardProxyPort": 1111,
  "forwardProxyUser": "zoom_proxyuser",
  "apiAddress": "https://api.zoom.us/v2/",
  "id": 1,
  "name": "Zoom Phone import",
  "type": "zoom_phones"
}

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 an Import Source entities can have different types with different object properties, for the password verification the verified property name has to be passed too with the checked plain password too.

POST https://VFC_MR_DOMAIN/verba/restapi/v1/importSources/1/password/verify
Content-Type: application/json
Accept: application/json

{
  "property": "apiSecret",
  "value": "new plain password"
}

...

Approach B: Organize the common server configurations to Configuration Profiles by server roles. This approach allows to maintain for maintaining the common configurations in on one location. The solution is recommended for deployments with multiple servers within.

...

The server configurations are stored in two location locations 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 locationlocations. A server configuration change in both approach approaches require 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.

Step 2: After the change, there can be a differences between the values in the central database and the registry values on certain servers. The differences has have to be resolved for every affected server configuration key by configuration key to decide which value should be pushed to the actual server registry. During the resolution process, configuration tasks have been created by the system for every affected server. These tasks contains contain actions for the affected services on the related server. After the configurations have been modified in the server’s registry, the services are needed to be notified about the configuration change to reread them.

Step 3: When the configuration tasks have been created for every server, these tasks have to be applied on to each server. After applying the new configuration values has been pushed to the local registry and the services reread the new values and started to work based on the new values.

The configuration passwords are stored in an encrypted format in the central database and the registry too. Contrary to the other entities the passwords are handled in a different way in the server configuration related endpoints. Numerous integrations require a connection string in a complex format instead of dedicated configuration values. These connection strings contain the passwords in an encrypted format with unencrypted configuration values separated with separator characters in one configuration value. Based on that at the backend side the , automatic password encryption is not possible. Due to that, the passwords have to been be encrypted by the client with the usage of the dedicated password encryption endpoint.

Another difference between the server configuration related endpoints and the other aforementioned introduced endpoints is the 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.

Server configuration examples

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

...

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

...

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

...

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

Retrieve the list of the differences in the certain server.

...

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.

...

"differences": []

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

...

If there is any item in the retrieved list, then those tasks have to be applied on to 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

...

modifications with a configuration profile

The steps and the basic strategy is are 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 similarly to the server configuration values by the registry path, but here the ID of the configuration profile is needed:

...

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.

...

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

...

Use case: Configure a fresh VFC server based on an existing other server’s configuration

In cloud-based solutions to decrease a server load a possible solution is to start a new serve server with the same role to balance the load during the peak times. This example shows a way how the configuration management can be achieved for a similar use case.

In the example deployment, the verbamr01 server exists. 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 in a configuration profile. In this case, firstly, the used configuration profile should be determine determined with the following request:

...

{
    "hostname": "verbamr01",
    "role": "MR",
    "configurationProfileId": 2,
    "description": null,
    "tasks": null
}

From this response, the configurationProfileId can be read out. That configuration profile can be set to the new server with the following requests. Firstly get the current server object from the new verbamr02.

...

Then change the configurationProfileId value in the object to the previously retrieved value and send it back for the update.

PUT https://VFC_MR_DOMAIN/verba/restapi/v1/servers
Content-Type: application/json

{
    "hostname": "verbamr02",
    "role": "MR",
    "configurationProfileId": 2,
    "description": "new server instance",
    "tasks": null
}

For this scaling scenario, the custom server configuration values should be collected and saved as a template. To retrieve these configuration configurations use the export endpoint.

Request:

...

That request only lists those configuration configurations that overwrite the configuration profile values. The configurations are stored in an XML schema.

...

That configuration list should be used as a template. After changing the values in the template it can be send sent for an import to the new server with the following request:

...