How can we help?

vSEC:CMS Client-Server Communication

Anthony - Versasec Support
Anthony - Versasec Support
  • Updated

Introduction

vSEC:CMS client-server architecture uses HTTP(S) as the underlying communication protocol. There are 2 protocol frameworks that can be used:

  • SOAP
  • gRPC

These protocols are supported when using vSEC:CMS User, vSEC:CMS Admin or Agent and vSEC:CMS Remote Security Device Management (RSDM).

Important
Starting March 2024, we will discontinue support for SOAP client interface. For optimal performance and compatibility, it is recommended to select force gRPC in the protocol dropdown list.
Recommendation
It is recommended to configure all of the above mentioned Windows services to Startup type of Automatic (Delayed Start). This ensures that the services will come back up after a system reboot.
Note
Historically, the vSEC:CMS User application was referred to as vSEC:CMS User Self-Service (USS). Similarly, the vSEC:CMS Admin and Agent applications were referred to as vSEC:CMS Operator Console (OC).

This article will describe how these protocols can be used when configuring your client-server architecture for vSEC:CMS.

Using gRPC

gRPC can be configured when using USS, OC and RSDM. You configure this when setting up these connections if they are to be used in your environment. In this article we will describe how this can be setup for the USS.

Note
The same configuration steps should be used if setting up OC and RSDM.

Configure Server-Side

From Options - Connections click the Add button and select User Self-Service and click Ok. Enable the Enable gRPC checkbox. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL if you wish to use HTTPS for secure communication between the client and server. The SSL certificate should be a machine web server certificate available on the vSEC:CMS server.

Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.

Important
If you use Microsoft CA you would need to use Microsoft Enhanced RSA and AES Cryptographic Provider as in below example. You should ensure that only this checkbox is selected in the template that will be used when issuing and renewing the SSL/TLS certificate used for the secure connection.

Important
If you are also configuring OC and/or RSDM (from Options - Connections) you need to use a different port for each service to what you configure for USS, i.e. a unique port number needs to be used for each service you use for gRPC. This is not the case if you are using SOAP where the same port can be used.
Important
When issuing a web server certificate for the vSEC:CMS server it is important that the Common Name (CN) of the certificate is unique for that server, otherwise you run the risk that the wrong certificate will be chosen. This is because of a limitation in OpenSSL which is used when searching for certificates in the local computer store. vSEC:CMS will use the subject of the certificate (CN) to establish the SSL connection to. Therefore it is also important that the subject of the certificate is resolvable from a DNS perspective from the client side.
Additionally, if SSL/TLS is used, the subject CN is case sensitive. For example, if the certificate subject CN for the SSL/TLS is Myserver.cms.com then you need to enter Myserver.cms.com and not myserver.com.com when configuring the connection URL below.
Note
It is possible to configure support for SOAP in parallel to using gRPC (simply enable it above and follow instructions below for SOAP). This will give you more flexibility in how your clients can be configured. For example, you can configure your clients to use gRPC and if for whatever reason gRPC service was not available the clients can fall back to use SOAP. If you plan to use such a configuration refer to the Installing the vSEC:CMS MSI Client article for details on how to enable this during client installations.

Configure Client-Side

On a client machine it will be necessary to install the vSEC:CMS User (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.

Open a command Window as administrator and change to the location where the MSI installer is located. Run the command similar to below

Command
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSGRPC="https://2016-server:8445" USSPCL=4

Where USSGRPC points to the backend gPRC service where vSEC:CMS is installed and USSPCL=4 configures the USS client to use gRPC.

Important
For optimal security you should configure the connection from clients to use SSL/TLS. In this case it is important that the full certificate chain (root and intermediate certificates) are available and trusted on the client host.
Note
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.
Note
If you are installing OC please refer to the article Install Operator Console for details on installing this component.

Using SOAP

As already mentioned above support for SOAP has been discontinued from March, 2024. You can still use SOAP but any issues encountered when using SOAP will not be supported. For historical reason we will keep this section here for information purposes only.

SOAP can be configured when using USS, RSDM and OC. You configure this when setting up these connections if they are to be used in your environment. In this article we will describe how this can be setup for the USS.

Note
The same configuration steps should be used if setting up RSDM and/or OC.

Configure Server-Side

From Options - Connections click the Add button and select User Self-Service and click Ok. Enable the Enable SOAP checkbox. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL if you wish to use HTTPS for secure communication between the client and server. If you use SSL it is important that the HostIP address field is entered with the name of the server as it appears in the SSL certificate. The SSL certificate should be a machine web server certificate available on the vSEC:CMS server.

Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.

Note
It is possible to configure support for gRPC in parallel to using SOAP (simply enable it above and follow instructions above for gRPC). This will give you more flexibility in how your clients can be configured. For example, you can configure your clients to use SOAP and if for whatever reason SOAP service is not available the clients can fall back to use gRPC. If you plan to use such a configuration refer to the Installing the vSEC:CMS MSI Client article for details on how to enable this during client installations.

Configure Client-Side

On a client machine it will be necessary to install the vSEC:CMS User Self-Service (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.

Open a command Window as administrator and change to the location where the MSI installer is located. Run the command similar to below

Command
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSSOAP="https://2016-server:8443/uss" USSPCL=3

Where USSSOAP points to the backend SOAP service where vSEC:CMS is installed and USSPCL=3 configures the USS client to use SOAP. Important to append /uss to the end of the server hostname/IP. 

Note
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.