AVAILABLE IN 9.8.0 AND LATER
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 applications that manages 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 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 how the credential management can be achieved for the different entities.
The following examples require a valid access token. To acquire an access token, use the Authentication endpoint. The different examples may require different permissions. Please, be aware to always use an access token that was acquired by a user with the right permissions.
User
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 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.
POST https://VFC_MR_DOMAIN//verba/restapi/v1/users/16/password/verify new plain password
Active Directory Synchronization Profile
The Active Directory Synchronization Profile entities contain credential data to be able to connect to an LDAP server or an Azure AD tenant. The updateable properties are various and depend on the type of the AD Synchronization Profile entity.
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 place immediately after a successful PATCH update request.
Request
PATCH https://VFC_MR_DOMAIN/verba/restapi/v1/adSyncProfiles/13F72189-2EEB-425F-885B-7D1BBA83DDEB
Content-Type: application/json
Accept: application/json
{
"userName": "john.doe",
"ldapPassword": "new plain password"
}
Response
{
"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.
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"
}
Storage Target
The VFC has numerous different Storage Target integrations which have different entity object schemas. These different schemas have different editable properties.
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 place immediately after a successful PATCH update request.
Request
PATCH https://VFC_MR_DOMAIN/verba/restapi/v1/storageTargets/11
Content-Type: application/json
Accept: application/json
{
"accessKeyId": "amazons3_storage_keyid",
"secretAccessKey": "new plain password"
}
Response
{
"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.
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"
}
Import Source
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 Zoom Phones import source in one request. The password has to be in plain format. The effect of the change take place immediately after a successful PATCH update request.
Request
PATCH https://VFC_MR_DOMAIN/verba/restapi/v1/importSources/1
Content-Type: application/json
Accept: application/json
{
"apiKey": "zoom_api_key",
"apiSecret": "new plain password"
}
Response
{
"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 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.
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"
}
Server Configuration
A VFC deployment usually contains multiple servers with different server roles. There are two strategies to maintain the configurations of these servers.
Approach A: Change the configurations individually by every server. The solution is not recommended for deployments with multiple servers within.
Approach B: Organize the common server configurations to Configuration Profiles by server roles. This approach allows to maintain the common configurations in on location. The solution is recommended for deployments with multiple servers within.
To read more about the topic visit the next page: Server and service configuration.
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. A server configuration change in both approach 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 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 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. The configuration tasks have to been applied for each servers. 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.