Install Agent Application

Introduction

Starting from version 6.1, vSEC:CMS can be installed on a host as a client Agent Application. This version serves as a lighter alternative to the full vSEC:CMS Admin Application, enabling operators to perform the following tasks:

• Life cycle operations.
• PIN unblock flows, both online and offline.
• Certificate flows.
• View credential information.
• Credential Updates.

The Agent Application can be configured to communicate securely with the vSEC:CMS Server using gRPC, with the option to enable or disable SSL/TLS encryption.

Installation

1. Start the vSEC:CMS installer on the client host and click I Agree.
2. Select the Agent: Agent interface to the server option and click Next.
3. Select the default location for the installation or click Browse to install to a different location. Click Install to begin the installation.
4. When it's finished, you can click Close.

Configuration

Starting from version 6.3, you can configure the connection settings by launching the application from the desktop shortcut. Upon launching the console for the first time, you will encounter a dialog similar to the one below.

Configuring gRPC connection to the vSEC:CMS Server:

1. From the Protocol dropdown list, select Force gRPC.
2. Locate the Server URL (gRPC) field in the dialog box.
3. Enter the URL of the backend server where gRPC is listening, in the following format.
   • http://<server-host>:<port-number>
   • https://<server-host>:<port-number> if SSL/TLS is enabled.
4. Once the URL is entered, click Test to check the connection.
5. After verifying the connection status, click Ok to finish setup.

By completing these instructions, you'll have successfully configured your gRPC connection to the vSEC:CMS Server, enabling seamless credential operations via vSEC:CMS Agent Application.

Silent Installation

It is possible to perform a silent install and configure the backend connection using the following parameters:

• /S: Use this parameter to initiate silent installation.
• -agent: Select Agent Application for installation.
• -grpc_client: Specifies the Server URL for the gRPC listener.
• -server_proto 4: Specifies the use of the gRPC protocol.

Silent Installation via PowerShell

Below is an example demonstrating the utilization of silent install parameters, in conjunction with the Server URL:

PS C:\> .\vSEC_CMS_Setup.exe /S -agent -grpc_client "https://vSEC-CMS:50550/" -server_proto 4

Registry Configuration

You also have the option to configure the Agent Application through the registry, utilizing either host-wide configurations or per-user settings.

Registry Path

For per-user configurations, use the following registry location:

[HKEY_CURRENT_USER\Software\Versatile Security\vSEC_CMS_T]

For host-wide configurations, use this registry location:

[HKEY_LOCAL_MACHINE\SOFTWARE\Versatile Security\vSEC_CMS_T]

Registry Settings

The registry values are:

• cms.adm.server.protocol: REG_DWORD
  • 4: Force gRPC
• grpc.adm.server.url: REG_SZ
  • http://<server-host>:<port-number>
  • https://<server-host>:<port-number>if SSL/TLS is enabled.

Agent Application Operations

The Agent Application is designed for operational tasks and does not support configuration changes to vSEC:CMS. Operators can perform various actions depending on their assigned roles, including issuing credentials, managing PINs, handling certificates, viewing credential details, and updating credentials. This makes it ideal for daily operational tasks.

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:

1. 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>

2. 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.
3. 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 
4. The URL entered on the client-side connection configuration SHOULD NOT contain a trailing / character. For example, if the back-end server is vSEC-CMS.mylab.com with port 8444 then the correct way to configure the connection URL is https://vSEC-CMS.mylab.com:8444 and not https://vSEC-CMS.mylab.com:8444/. 
5. 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>