Migrate Clients from SOAP to gRPC

Introduction

From April 2024 vSEC:CMS will stop supporting clients that use SOAP for the communication protocol between clients and the server. It will be required to change all clients to use gRPC for the communication protocol. This article will describe how this can be performed.

Important
SOAP communication protocol will continue to function but we will not support resolving any issues that may arise when using SOAP in a customer environment. Therefore it is important to transition to gRPC as described in this article.

Prerequisite

It is required that you are running the latest versions of vSEC:CMS both on the server and client(s) before making the switch over to use gRPC. See the article for details on updating your system here.

Check Current Configuration

Server-Side

The first question to ask yourself is how do I know what, if any, client components are used in my environment? You can check what is configured currently by logging onto the server and opening the vSEC:CMS Admin console. Navigate to Options - Connections and see what connectors are configured in your environment.

3 possible connections need to be edited/changed:

Operator Console Service (OCS)
User Self-Service (USS)
RSDM Service (RSDM)

Important
You may be using the API Service which uses our SOAP API for external systems that interface to vSEC:CMS. If you are using this component we will continue to maintain this feature but will not be adding any new features to it. It is recommended to transition to our REST API. See the article here for further details on using this.

For OCS, USS or RSDM check if Enable SOAP is enabled in your connection dialog (see below example).

If you don't have anything configured for OCS, USS, or RSDM then you don't need to do anything on your system.

Client-Side

On clients, you can check what is configured by opening a command prompt as administrator on a client and running the following commands:

For vSEC:CMS User application:

PS C:\Program Files\Versasec\vSEC_CMS Self-service>vSEC_CMS_T_USS.exe -configure

Check the Server tab to see what is currently configured.

For Admin application:

PS C:\Program Files\Versasec\vSEC_CMS S-Series>vSEC_CMS_T.exe -configure

For Agent application:

PS C:\Program Files\Versasec\vSEC_CMS S-Series>vSEC_CMS_T_LITE.exe -configure

You should now have all of the information required to move to the next stage.

Configure gRPC Only on Server

Depending on what client services you use, this section will describe how you can configure vSEC:CMS to use gRPC as the communication protocol between clients and the server.

Step 1 - Configure SSL/TLS Certificate

It is recommended to configure the communication between the clients and server to be secure. To ensure this, a certificate needs to be available in the Computer account certificate store where the vSEC:CMS server is installed.

It is recommended to issue a web server certificate for the secure connection.

Important
When issuing a web server certificate the Common Name (CN) of the certificate must be 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 uses the subject of the certificate (CN) to establish a secure connection. Therefore the subject of the certificate must be resolvable from a DNS perspective from the client side.
Additionally, the subject CN is case-sensitive. For example, if the certificate subject CN is Myserver.cms.com then you need to enter Myserver.cms.com and not myserver.com.com when configuring the connection from vSEC:CMS client applications.

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

Step 2 - Configure Connection Settings from Server-Side

This section will describe how you can configure the connection settings from the server-side. We will describe how you can do this for the OCS. The same changes need to be made if you are using USS or RSDM.

RDP to the server where vSEC:CMS is installed and log onto the Admin console. Navigate to Options - Connections and select Operator Console Service.

Uncheck Enable SOAP if the check box is already enabled.

Check Enable gRPC and enter the name of the server (the exact, case-sensitive name (CN) that was used when issuing the certificate) into the HostIP address field.

Enter a unique port number into the gRPC Port field.

Important
You need to use a unique port for each gRPC service that you use. Therefore, if you are using OCS and USS then you would need to have a different port configured for each service.

Enable Use SSL and select the certificate to be used from the available drop-down list.

Click OK to save and close.

Open the Windows services console on the server and start (or restart if it is already running) the service named vSEC:CMS Operator Console Service.

Note
If the Windows services don't start for whatever reason, try restarting the core service vSEC:CMS Service. Once this is up and running try starting the other service(s).

Step 3 - Configure Connection Settings from Client-Side

The next step is to configure any client(s) to use gRPC. We will describe how to do this for the 3 different client components that you may already use. We will describe how to set the initial connection so you can validate that the communication between the client and the server is fully operational.

Note
Once you validate that gRPC communication is functional from a client to the backend server, it is recommended to push these changes via GPO. Refer to the article here which describes how you can perform this.

vSEC:CMS Admin or Agent Application

Open a command prompt on a client where vSEC:CMS Admin or Agent Application is already installed. Change the directory to the root of the installation folder and run the following command.

For vSEC:CMS Admin application:

PS C:\Program Files\Versasec\vSEC_CMS Self-service> .\vSEC_CMS_T_USS.exe -configure

For vSEC:CMS Agent application:

PS C:\Program Files\Versasec\vSEC_CMS Self-service> .\vSEC_CMS_T_LITE.exe -configure

This will open a configuration dialog.

Select Force gRPC for the Protocol from the drop-down list.

In the Server URL (gRPC) enter the URL and port to connect to the backend service. Click the Test button. If the communication is operational you should get a success message.

Click OK to save and close the configuration changes.

vSEC:CMS User Application

Open a command prompt on a client where vSEC:CMS User Application is already installed. Change the directory to the root of the installation folder and run the following command.

PS C:\Program Files\Versasec\vSEC_CMS Self-service> .\vSEC_CMS_T_USS.exe -configure

This will open a configuration dialog.

Go to the Server tab.

Select Force gRPC for the Protocol from the drop-down list.

In the Server URL (gRPC) enter the URL and port to connect to the backend service. Click the Test button. If the communication is operational you should get a success message.

Click OK to save and close the configuration changes.

vSEC:CMS RSDM

The RSDM component is used in environments where virtual smart cards are managed by vSEC:CMS. In those environments you need to edit the connection parameters via registry. On a client where RSDM is running make sure to configure the registry settings:

DWORD: cms.server.protocol

String: grpc.server.url

Located here:

[HKEY_LOCAL_MACHINE\SOFTWARE\Versatile Security\vSEC_CMS_RSDM\Service]

The value for cms.server.protocol should be 4 and in grpc.server.url enter the connection URL for the backend service.

Restart the vSEC:CMS Remote Security Device Management on the client and ensure that the connection is established. You can verify this from Windows Event Viewer under Windows Logs - Application. You should see something similar to below:

Troubleshooting gRPC Connection Issues

Once you have completed the above configurations you may still get connection issues when testing from clients. You may see a generic error message like below when testing the connection for the clients:

This can occur for a few reasons. If you encounter this error please check the following:

Make sure the port that gRPC is listening on is open. You can use a PowerShell command to verify that the port is open by running below, where <server-ip> is the IP of the server that vSEC:CMS is running on and <grpc-port> is the port it is listening on. You should get a response that the test succeeded ok if everything is ok (TcpTestSucceeded : True).
```
Test-NetConnection -ComputerName <server-ip> -Port <grpc-port>
```
On the client make sure that you have the sub and root CA certificates installed in the local user store that the client is running on. Also, important to not have old expired sub or root CA certificates installed on the clients as these can be selected during the handshake resulting in failure to setup the connection. Therefore, you should only have valid sub and root certificates in the user store and any old/expired sub and root certificates should be removed.
Make sure the name entered in the connection URL settings for the server name match exactly (case-sensitive) what is in the CN for the certificate subject field. For example, if the CN is set to my-vSEC-CMS.mylab.com then the connection URL name should be exactly like what is set in the CN, https://vSEC-CMS.mylab.com:8444
Make sure that the certificate template used to issue the certificate on the vSEC:CMS server was issued as either Microsoft Enhanced RSA and AES Cryptographic Provider or Microsoft Enhanced Cryptographic Provider v1.0 provider. It can be that for some reason the certificate gets issued into a different provider store and this can cause the loading of the certificate to fail. To ensure that the certificate is installed into the correct provider store, issue the certificate as a .pfx. Then remove any certificates from the computer store of the vSEC:CMS server that had been issued before for vSEC:CMS server. Open a command prompt on the server and run below command to import the certificate into the correct provider store:
```
certutil.exe -csp "Microsoft Enhanced RSA and AES Cryptographic Provider" -importPFX <my-server.pfx>
Or
certutil.exe -csp "Microsoft Enhanced Cryptographic Provider v1.0" -importPFX <my-server.pfx>
```

Search