vSEC:CMS User Application

Overview

Users can manage their credentials and perform self-service functions using the vSEC:CMS User Application. This includes:

• Credential issuance
• Credential renewal and update
• Credential PIN reset
• Credential retirement

An overview of the architecture is provided in the diagram below.

The vSEC:CMS User Application is a client native to Windows. It is used by users to manage their credentials. The client communicates with the vSEC:CMS server component either through a SOAP interface or a gRPC interface. It is recommended to use gRPC as it offers higher performance advantages compared to the traditional SOAP protocol.

Installation

The vSEC:CMS User Application is installed using a Windows Installer Package. Please refer to the article Installing the vSEC:CMS User Application for detailed instructions.

Configuration Client-Side

It is possible to configure specific settings for your vSEC:CMS User Application deployment. You can achieve this by passing the -configure parameter when starting the User Application.

Open a command prompt as administrator and navigate to the location where vSEC:CMS User Application is installed, then run:

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

Settings

From the Settings tab, several configuration options are available.

Update Check

In this section, you can configure how the vSEC:CMS User Application behaves when it starts and the user attaches their credential.

The following options are available:

• Do not select any of the options: In this case, the User Application will not perform any check on the user credential when attached.
• Select Check for PIN Change: The User Application will verify if the user needs to change the PIN on the credential when it is attached to the user's computer. For instance, if a flag is set on the credential to change the PIN on first use, the User Application will notify the user to change their PIN. This feature requires support for changing the PIN on first use by the credential.
• Select Check for PIN Unblock: The User Application will check if the user needs to unblock the PIN on the credential when it is attached to the user's computer. If the PIN is blocked, a popup will inform the user that they need to unblock the PIN.
• Select Check for card update: The User Application will examine if there are any pending updates to be performed on the credential, such as certificate renewal.

Clicking the Configure button presents more options. From here you can configure how the update should be presented to the end user. 

Hidden Credential Readers

If there is a need to limit a user's access to a specific credential reader, click the Configure button. This action will open a dialog displaying a list of all connected credential readers on your computer. Choose the reader(s) that should not be available when using the vSEC:CMS User Application.

Credential Access

From the Credential Access section, it is possible to configure how the vSEC:CMS User Application will attempt to communicate with the credential. Communication with the credential can occur either natively or through the credential minidriver. Depending on the credential being used, it will be necessary to set the correct access type for communication.

The configurations available are:

Force minidriver usage: The User Application will only use the credential minidriver installed on the user's computer if this option is configured. If there is no minidriver available then no operations will be possible with the credential.

Use minidriver if possible: The User Application will attempt to use the credential minidriver installed on the user's computer if this option is configured. If there is no minidriver installed then the application will attempt to use native access. If native access is not supported for the credential then no operations will be possible with the credential.

Use native access if possible: The User Application will attempt to use native access to the credential if this option is configured. If native access to the credential is not supported then the application will attempt to use the minidriver interface. If there is no minidriver available then no operations will be possible with the credential.

Force native access: The User Application will only use native access to the credential if this option is configured. If native access to the credential is not supported then no operations will be possible with the credential.

Enabling Challenge/Response for PUC-Based Unblock

To unblock PUC-only credentials, such as PIV tokens, enable Challenge/Response for Offline PUC-based Unblock in vSEC:CMS User Application.

This feature must also be activated on the server side. Access it via Options - Security in vSEC:CMS Admin Application.

Permissions

From the Permissions tab, various configuration options are accessible. The table below lists all default functionalities available in the vSEC:CMS User Application.

Server Connections

From the Server tab, several configuration options are available.

Here, you will configure the URL of the vSEC:CMS service that the vSEC:CMS User Application will communicate with when performing self-service operations, as well as the protocol that will be used for this communication.

• Prefer SOAP: The User Application will attempt to use SOAP, and if communication via SOAP is not possible, it will then attempt to use gRPC.
• Prefer gRPC: The User Application will attempt to use gRPC, and if communication via gRPC is not possible, it will then attempt to use SOAP.
• Force SOAP: The User Application will attempt to use SOAP, and if communication via SOAP is not possible, it will fail to communicate.
• Force gRPC: The User Application will attempt to use gRPC, and if communication via gRPC is not possible, it will fail to communicate.

If the vSEC:CMS server has an IP address of 172.0.0.10, and you want to connect to it through HTTP access on port 8080 using the SOAP protocol, you need to enter the following details in the Server URL (SOAP) field:

http://172.0.0.10:8080/uss

Add /uss after the hostname/IP address and port number for SOAP configuration. Ensure communication with the backend URL by clicking Test, with successful validation confirmed in a dialog.

For gRPC only connection, enter the hostname/IP along with the configured port in the Server URL (gRPC) field:

http://172.0.0.10:8080

If vSEC:CMS is configured to use both SOAP and gRPC, a separate port for gRPC must be set in the Server URL (gRPC) field:

http://172.0.0.10:8081

Verify backend URL communication by clicking Test, with successful validation acknowledged in a dialog.

Windows Registry Reference

The registry value names are: 

• grpc.server.url
• soap.server.url
• cms.server.protocol can have four different values:

1. Prefer SOAP
2. Prefer gRPC
3. Force SOAP
4. Force gRPC

System Tray Mode

In many scenarios, it will be necessary to have the vSEC:CMS User Application running in the system tray. This can be achieved by passing the parameter -s to the executable. For example, open a command prompt as administrator and navigate to the installation location of the application, typically:

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

Normally, this can be scripted and pushed out as part of your software deployment.

Enable System Tray Mode with GPO

To enable system tray mode with Group Policy Object (GPO), use either Computer Configuration or User Configuration - Policies - Administrative Templates - System - Logon - Run these programs at user logon.

Enable System Tray Mode with Application Shortcut

To enable system tray mode using an application shortcut, you need to add a shortcut to the vSEC:CMS User Application executable, vSEC_CMS_T_USS.exe, in the specified location:

C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp

Autoconnect Mode

Users often log onto their client before establishing a backend connection, like logging into a VPN first. In this scenario, an error dialog appears if the connection fails. To address this, use the -autoconnect parameter to enable auto-reconnect upon successful connection.

The target should look like the below if vSEC:CMS User Application is installed in the default location:

"C:\Program Files\Versasec\vSEC_CMS Self-service\vSEC_CMS_T_USS.exe" -s -autoconnect

System Tray Options

Upon accessing the vSEC:CMS User Application icon in system tray mode, users will discover a multitude of available options, including:

• Show User Application: This will open the main application on the Home page.
• Credential Details: This will open the main application on the Credential page.
• Diagnostic: This will open the Diagnostic dialog (see the Diagnostic section below for further details).
• Clean Configuration Cache: This will flush the cache which can be required if the User Application cache gets corrupted over time.
• Help: This will open the help page on the default browser of the client.
• Online Knowledge Base: This will open an online knowledge page.
• About: This will show version information about the application.
• Exit: This will close the application

Diagnostic

You can obtain useful details and generate trace logs for troubleshooting issues with the vSEC:CMS User Application from the Diagnostic dialog.

System Info provides crucial details for troubleshooting vSEC:CMS User Application issues. You might also need to create trace logs. Simply click Start Trace, then Close. Reproduce the issue, return to Diagnostic, click Stop Trace, and Save the trace file.

Share it with your partner for troubleshooting analysis.

Kiosk Mode

Kiosk Mode in vSEC:CMS User Application transforms your computer into a dedicated platform solely for credential management tasks within the application. By activating this mode, the computer is restricted to performing only essential functions related to managing credentials, ensuring heightened security and focused usability.

Configure Kiosk Mode

To configure vSEC:CMS User Application for kiosk mode, create a file named cms_app.cfg, and push/copy it to vSEC:CMS User Application installation directory. Typically:

C:\Program Files\Versasec\vSEC_CMS Self-service

Use the following content for the file:

<?xml version="1.0" encoding="UTF-8"?>
<config>
<factory signature="FACTORY_SIGNATURE">
<std/>
<force/>
</factory>
<oem>
<std></std>
<force>
<option>
<gui>
<mode>0x00000001</mode>
</gui>
</option>
</force>
</oem>
</config>

The <gui> section controls the mode in which the application will run.

• Kiosk Mode: 0x00000001
• Normal Mode: 0x00000000

Customise User Application Layout

You have the flexibility to customize the layout of the vSEC:CMS User Application, including background images on all tabs and an additional image on the Home tab. Here are the available options:

Customizing Background Images

• Types of Images: You can use .svg or .png files for background images.
• Manual Configuration: Customize the images manually.
• GPO Configuration: Customize the images via Group Policy Objects (GPO). Refer to the article Configure Windows GPO under the Configure Background Image section.
• File Placement:
  • Background images should be named:
    • vSEC_CMS_T_USS.exe-bgv.svg or vSEC_CMS_T_USS.exe-bgv.png for the tab background.
    • vSEC_CMS_T_USS.exe-home.svg or vSEC_CMS_T_USS.exe-home.png for the Home tab.
  • Place these files in the installation folder, typically located at:

C:\Program Files\Versasec\vSEC_CMS Self-service

Configuring Background Image Position

The position of the background image and its display location can be configured via configuration files.

Background Image Position:

• * : TILE and only shown in Home tab.
• 0 : TILE and shown in ALL available tabs.
• 1 : TOPLEFT and shown in ALL available tabs.
• 2 : TOPRIGHT and shown in ALL available tabs.
• 3 : BOTTOMLEFT and shown in ALL available tabs.
• 4 : BOTTOMRIGHT and shown in ALL available tabs.
• 5 : VS_CENTER and shown in ALL available tabs.

The position of the additional image that can be displayed on the Home tab can be configured by setting the values below in a config file named vSEC_CMS_T_USS.exe-home.cfg. This file needs to be placed in the installation folder, normally located here:

C:\Program Files\Versasec\vSEC_CMS Self-service

• 1 : TOPLEFT;
• 2 : TOPRIGHT;
• 3 : BOTTOMLEFT;
• 4 : BOTTOMRIGHT;
• 5 : CENTER.

If you plan to use a background image that will be displayed on the entire tab page then you do not need to configure the file vSEC_CMS_T_USS.exe-bgv.cfg.

For example, if you wish to have a company logo ACME displayed on the Home page and a custom background image displayed on all Tabs then you would set this up as described below. Lets say the company logo is as below

and the background image is like below

then save the company logo image as vSEC_CMS_T_USS.exe-home.png and the background image as vSEC_CMS_T_USS.exe-bgv.png. Additionally, you will need to have the config file vSEC_CMS_T_USS.exe-home.cfg with a value of 5 such that the image will be displayed in the centre of the Home tab. These files will need to be copied to all clients where the application is to be used and they should be placed in the installation folder, normally located here: C:\Program Files\Versasec\vSEC_CMS Self-service. 

Configure User Application Server-Side

If User App is to be used then it will be required to configure this on the server-side in the credential template. In this section the different configuration options will be described.

In order to enable User App support for a credential template go to Templates - Card Template and in the General section click the Manage button.

Click the Add button. Enter a name in the Template name field.

If it is required that the end user will be allowed to self issue their credential from the User App client then enable Self-issuance enabled. Additionally, if it is required that the end user will be allowed to retire their credential from the User App client then enable the Retire card enabled checkbox. These functions will be performed from the Credential page in the User App application.

Important
If self-issuance is enabled it will be required to enable Issue by User(s) in the Issue Card section of the credential template. See the article Manage Hardware Credentials using vSEC:CMS User Self-Service for a complete example of how this might be configured in a real-life scenario.

In the User Authentication for PIN Unblock section 4 options are available from the drop-down list, Use passphrase to authenticate user, Use windows credentials to authenticate user, Use a smartcard challenge/response and OIDC Connection (OAuth).

Use passphrase to authenticate user

Select the Use passphrase to authenticate user if it is required that the user who is performing the unblock operation from the User App application is required to enter a passphrase to authenticate during the unblock procedure. A number of options will be available when you select this option.

Enable User can choose smartcard challenge/response if the User App gives the user an option to use this mechanism to perform PIN reset.

Enable System generates passphrase at card issuance if the User App should generate a passphrase for the user when issuing the user's credential.

Enable User may change passphrase checkbox if the user is allowed to change their passphrase from the User App (from the Credential page).

Click the Deliver button to create an email or SMS template that will be used to send the generated passphrase to the user at credential issuance. See the section below for further details on this.

Email and SMS Template Configuration

If it is planned to send notifications to the end user via email or SMS then follow the instructions in this section.

Add Email Passphrase Notification Template:

Click the Add button to add a template.

Enter a template name and select the Outgoing Email Server from the drop-down list. The email server connection will need to be already configured from Options - Connections - Email.

Click the Edit email template button.

Enter a From email address and enter the variable name that should be used to retrieve the user email from the user directory. Enter a CC and BCC if required. Enter an appropriate subject for the email.

For the email body, two options are available - HTML or text. If HTML is selected it will be necessary to import an MHT file that contains the content of the email body. MHT files can be created using MS Word for example. vSEC:CMS variable names can be used which will be replaced with actual data, for example, the user's name can be retrieved from the user directory.

If text is selected enter the appropriate message body and use vSEC:CMS variables to populate specific details such as the user's name for example.

Click OK to save the email template and click Save to close and save.

Add SMS Notification Template:

Click the Add button to add a template.

Enter a template name and select SMS from the drop-down list.

Click the Manage button and click Add to add an SMS provider.

Enter a template name and the Service address and Service mobile address fields will automatically be entered with the details for TeleSign. In the Credentials section enter the credentials as provided by TeleSign. Click Save to save and close the dialog. Then from the drop-down list for SMS Provider select the template just created.

For the other supported SMS providers (Certificall, Clickatell, Tyntec, and Dolphin) the protocol used is SMS over HTTP as this is the protocol supported by these providers. If additional providers not listed here do support SMS over HTTP then the generic HTTP provider can be configured. Sample configurations have been pre-set for the providers supported. It is necessary to check with your provider to determine what parameters are required.

For example, if you are using Clickatell as your provider then enter a template name and select Clickatell from the available SMS providers. Enter the service address and the protocol required. In the Parameters section pre-set parameters are already provided. The user, password, and api_id need to be configured with your specific credentials. The to and text will be assigned to variables mapped to attributes as the phone number will need to be retrieved for the user typically from a user directory and the text needs to be retrieved.

Click the Edit SMS template button to create an SMS message template. Enter a phone number in the Phone number field. This would typically be a variable that is mapped to an attribute in the user directory. In the message window enter the message content that you wish to send. From the Variables drop-down list select a variable that is required and click the Copy button to copy the variable value which can then be pasted into the message window. Click OK to save the settings.

Configure Passphrase Policy

Click the Policy button to configure a passphrase policy that needs to be met when the user sets their passphrase. By enabling the Adjacent positions allowed check box a passphrase that has repeated characters adjacent to one another will be allowed. Enter the number of allowed adjacent positions in the Allowed repetitions field. The value entered will set the number of times that a character can be repeated in adjacent positions. For example, if this value is set to 4 then 1111c1 and aaaa1a are allowed passphrase values, and 11111c and aaaaa1 are not allowed passphrase values.

The Max appearance configures the passphrase policy to set the allowed number of appearances of a character in a passphrase but it is not possible to specify which character. For example, if the value for Max appearance is set to 2 then the passphrase value 0001 would not be allowed whereas the passphrase value 0011 would be allowed.

The Max length of sequence is the number of times that a sequence of characters is allowed, for example 1,2,3,4,5,6...For example, if this parameter is set to 4 then 1234c5 and abcd1e are allowed passphrase values and 12345c and abcde1 are not allowed passphrase values.

The Max repeated characters configure the passphrase policy to set the number of different characters that can be repeated at least once. For example, if this value is set to 1 this means one character can be repeated but it is not possible to specify which one.

The Tries counter configures the passphrase policy to set the number of incorrect passphrase entry attempts a user can attempt before the flow will be terminated. The user will then need to request resetting of the passphrase.

Enable the Character set restrictions checkbox in order to be able to configure specific character combinations to be used when setting a passphrase. If this checkbox is not enabled then all characters will be allowed to be used when setting a passphrase.

If the Character set restrictions checkbox is enabled then it is possible to configure specific allowed characters when setting a passphrase. These can be set to either Allowed or Mandatory or both. If Alphabetic uppercase is enabled then the passphrase must contain an upper-case character. If Alphabetic lowercase is enabled then the passphrase must contain a lower-case character. If None alphabetic is enabled then the passphrase must contain a character that is neither numeric or alphabetic, for example, any of these characters would qualify in this case - !"£$%^&*(). If None Ascii is enabled then the passphrase must contain a non-ascii character.

The New passphrase must differ checkbox configures the passphrase policy, if enabled, to ensure that the new passphrase entered is not the same as the previous passphrase set.

For Passphrase length, the Min configures the passphrase policy to set the minimum length that the passphrase needs to be when the user is setting their passphrase and the Max configures the passphrase policy to set the allowed maximum length that the passphrase can be when the user is setting their passphrase.

Use Windows credentials to authenticate user

Select Use Windows credentials to authenticate user if it is required for the user to provide their Windows domain username and password as the authentication credential during the smart card unblock flow.

Use smartcard challenge/response

Select Use smartcard challenge/response if it is required for the user to perform the unblock via a helpdesk type flow. The flow in this case will be similar to the flow when the user is offline. See the article Perform PIN Unblock and look in the section Offline PIN Reset for details on what that flow will look like.

PIN Unblock Codes

In the PIN Unblock Codes section several options are available.

Enable the Enable checkbox to configure the support of this feature.

Click the Expiration button to configure the lifetime for an unblock code that can be generated and provided to the credential holder. Different methods of how unblock codes can be sent are described in the sections below. You can configure the lifetime to minutes, hours, days and weeks.

User may request unblock code via console:

Enable the User may request unblock code via console if the user who the credential is issued to is allowed to request unblock code from the User App. Enable the Approval checkbox if it is required that any request for an unblock code from a user requires approval before the code is provided to the user. Click the Configure button to configure the approval as would be set in a Windows AD environment. See the section below Configure Approval in AD Environment for further details on this.

Enable the Force authentication checkbox if it is required that the user needs to authenticate before they can proceed with an unblock request. Depending on what authentication mechanism is configured in the User Authentication for PIN Unblock the user will be prompted to present an authentication credential. Enable the Deliver checkbox if it is required to configure an email or SMS template that can be used to send an email or SMS to the user with the unblock code when they request an unblock code. See the section Email and SMS Template Configuration above for details on this.

Operator may generate unblock codes

A user whose credential is blocked may request an unblock code in order to unblock the credential. This would typically be conducted through a dedicated helpdesk service.

Enable the Operator may generate unblock codes if it is to be allowed for operators with the appropriate permissions to generate PIN unblock codes for user credentials issued and managed by the vSEC:CMS. Enable the Show code checkbox if the PIN unblock code will be displayed to the operator when they request the PIN unblock code from Actions - Smart Card Unblock. The operator would then need to provide this code back to the user in order for them to perform the PIN unblock.

Enable Enforce usage if exists if is allowed for an operator to generate an unblock code for a managed credential when the end user, via the self-service, does not remember their authentication credentials to perform an online unblock. In this case the end user can contact their helpdesk and request that an unblock code is generated and provided back. This then will be used to unblock the managed credential.

Enable the Deliver check box if it is required to configure an email or SMS template that can be used to send an email or SMS to the user with the unblock code when the operator requests an unblock code. Enable the Deliver at issuance check box to configure the vSEC:CMS to send an email or SMS of an unblock code that will be sent when the credential is issued for the first time. Enable the Deliver manually checkbox if it is required to send an unblock code to the credential holder via email or SMS. Click the Configure button to configure the channel that the unblock code will be sent through. Click the Test button to perform a test to ensure that the configured delivery channels are functional. Refer to the article Delivery of Smart Card Unblock Codes for more details on this particular feature.

For email or SMS configuration see the section Email and SMS Template Configuration above for details on this.

Configure Approval in AD Environment

In this section guidelines on how to configure approval workflows in a Window AD environment are provided.

Users

In the table below the test users in this example and their locations in terms of organizational units (OU) are listed. The OU help-desks are supposed to be the users that are not allowed to get approval of admins for self-service tasks. In the OU called self-service are the users that are supposed to be allowed to perform self-service tasks which are approved by admins from the group Admins.

Permission Configuration:

The permission selected is the built in Windows permission Reset password. Any extended permission can be used which is configurable in the vSEC:CMS.

Below are examples of permissions on OU=help-desk and for OU=self-service for the Admins group:

Validating Permissions in AD:

You can check that the permissions are correctly configured by checking the Effective Permissions on the users in the user object for the Admin Group.

Validating Permission Using vSEC:CMS

It is possible to validate permissions from the vSEC:CMS to ensure that the environment is configured correctly. When the vSEC:CMS is configured for approval it is possible to validate the permissions configured.

Select the Extended Rights configured from the available drop-down list and enable Self approval not allowed if it is required that all unblock PIN requests require approval from another person, i.e. it will not be possible for a person to approve their own approval request. In the Test Permission section, it is possible to test with actual users. For requester click the Get button to select a user who can request PIN unblock. For Approver click the Get button to select a user who can approve such a request and click Check Permission button. If the Windows server environment is configured correctly a success dialog will be presented.