Overview

Using vSEC:CMS User application (referred to as the User App in this article) it is possible for a user to manage their credential. From the User App the user can perform typical self-service functions such as:

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

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

User App is a Windows native client. It will be deployed to any client where a user will manage their own credential from. It communicates with the vSEC:CMS server component either through a SOAP interface or through a gRPC interface. It is recommended that you use gRPC as this has higher performance advantages over the more traditional SOAP protocol.

Installation

User App is packaged into an MSI installer. See the article Installing the vSEC:CMS MSI Client for details on how to use the MSI to install User App.

Configuration Client-Side

It is possible to configure specific settings that you require to be available in your User App deployment. You can configure the available settings by passing in -configure parameter when starting the User App.

Open a command prompt as administrator and go to the location where User App is installed, typically C:\Program Files\Versasec\vSEC_CMS Self-service.

Settings

From the Settings tab a number of configuration options are available.

Update Check

In this section, it is possible to configure the behaviour of the User App when the application is started and the user attaches their credential.

The following options are available:

• Do not select any of the options such that the User App will not perform any check on the user credential when attached;
• Select Check for PIN Change. The User App will check if it is required for the user to change the PIN on the credential when the credential is attached to the user's computer. For example, it is possible to set a flag on the credential to change the credential PIN on first use. If this is set on the credential the User App will notify the user that they need to change their PIN. The credential used will need to support the change PIN on first use feature;
• Select Check for PIN Unblock. The User App will check if it is required for the user to unblock their PIN on the credential when the credential 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 App will check to see if there are any updates pending that need 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. 

The update can be either a balloon style dialog that appears for a few seconds and then disappears or a popup style dialog. For the popup style dialog you can set in such a way that it will always be on top meaning the user needs to act on the dialog thereby enforcing the user to not ignore the message.

Hidden Credential Readers

If it is required to restrict what credential reader(s) a user can have access to click the Configure button. This will open a dialog with a list of all available credential readers connected to your computer. Select which reader(s) that should not be available when using the User App.

Credential Access

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

The configurations available are:

Force minidriver usage: The User App 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 App 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 User App 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 App will attempt to use the native access to the credential if this option is configured. If native access to the credential is not supported then the User App 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 App will only use the 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.

Enable the Enable challenge/response for offline PUC based unblock if it is required to be able to perform credential unblock using challenge/response for PUC only supported credentials. For example, PIV tokens only support unblock through PUC. But using this configuration in the User App it will be possible to use challenge/response. Additionally, it will be necessary to enable support for this feature on the server side. The Enable challenge/response for offline PUC based unblock setting would need to be enabled on the vSEC:CMS from the Options – Security page using the Admin Console.

Permissions

From the Permissions tab a number of configuration options are available. The table below lists all available functionality by default that is available in the User App.

Server

From the Server tab a number of configuration options are available.

Here you will configure the URL of the vSEC:CMS service that the User App will communicate with when performing self-service operations and the protocol that will be used for the communication.

Select Prefer Soap which will result in the User App attempting to use SOAP and if it cannot communicate via SOAP then it will attempt to use gRPC;

Select Prefer gRPC which will result in the User App attempting to use gRPC and if it cannot communicate via gRPC then it will attempt to use SOAP;

Select Force Soap which will result in the User App attempting to use SOAP and if it cannot communicate via SOAP then it will fail to communicate;

Select Force gRPC which will result in the User App attempting to use SOAP and if it cannot communicate via SOAP then it will fail to communicate.

For example, if the vSEC:CMS server has an IP address of 172.0.0.10 and the connection on the vSEC:CMS is configured for HTTP access on port 8080 using SOAP protocol, then the following should be entered into the Server URL (SOAP) field: http://172.0.0.10:8080/uss

It is necessary to add /uss after the host name/IP address and port number when configuring SOAP. Click the Test button to test if the communication to the backend URL is successful. You will get a success dialog if it is possible to communicate with the backend.

For gRPC URL only enter the host name/IP address along with the port in the field provided. For example, if the vSEC:CMS server has an IP address of 172.0.0.10 and the connection on the vSEC:CMS is configured for HTTP access on port 8080 using SOAP protocol, then the following should be entered into the Server URL (gRPC) field:

http://172.0.0.10:8081

Click the Test button to test if the communication to the backend URL is successful. You will get a success dialog if it is possible to communicate with the backend.

System Tray Mode

In a lot of scenarios it will be required to have the User App running in the system tray. It is possible to start User App in system tray mode by passing the parameter -s to the User App executable. For example, open a command prompt as administrator and go to the location where the User App is installed, typically here C:\Program Files\Versasec\vSEC_CMS Self-service.

Normally, this can be scripted and pushed out as part of your software deployment. For example purposes, if all users that log onto a client should have the User App running in the system tray then you would need to add a shortcut to the User App executable vSEC_CMS_T_User App.exe in the folder C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp.

Additionally, it may be common that you log onto your client without having established a connection to your backend, for example you need to log into your VPN first. In this case the end user will receive an error dialog that connection could not be established. Later when you have established a connection to your backend the User App will not reconnect with the backend. In this case you should pass in an additional parameter -autoconnect. This will suppress the error message when a connection could not be made and then when the connection comes up the User App will auto connect.

The target should look like below if the User App is installed into the default location:

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

From the User App icon available when in system tray mode a number of options will be available.

These are:

• Show User Application: will open the main User App console at the Home page;
• Credential Details: will open the main User App console at the Credential page;
• Diagnostic: 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 App cache gets corrupted over time;
• Help: this will open help page on the default browser of the client;
• Online Knowledge Base: this will open online knowledge page on the default browser of the client;
• About: this will show version information about the User App;
• Exit: this will close the User App.

Diagnostic

From the Diagnostic dialog you can get useful details and generate trace logs when troubleshooting issues with User App.

From System Info you can see different details that can be useful when investigating issues with the User App.

Additionally, it may be requested to generate trace logging. Click the Start trace button and then Close. Then recreate the issue you face. Go back to Diagnostic and click Stop trace and Save. Save the trace file and provide to your partner who requested the trace file for analysis.

Suppress Warnings at Startup

If the User App is configured to connect to the vSEC:CMS backend and for whatever reason the client is offline then when starting the User App a message dialog will be displayed warning the user that the User App could not connect to the vSEC:CMS. This message dialog can be suppressed by passing in a parameter -autoconnect when starting the application. For example, open a command prompt as administrator and go to the location where User App is installed, typically C:\Program Files\Versasec\vSEC_CMS Self-service.

Additionally, starting the User App with this parameter will allow the User App to reconnect to the backend if and when the backend is available.

Configure User App in Kiosk Mode

If it is required to configure the User App to be used in kiosk mode it will be necessary to include a file named cms_app.cfg and this should be placed beside the User App executable file which is typically installed to C:\Program Files\Versasec\vSEC_CMS vSEC:CMS.

The contents of the file should be similar to below:

The section <gui> needs to be set with the value 0x00000001 if the User App should be run in kiosk mode. In order to run the User App in normal mode then change this value to 0x00000000.

Customise User App Layout

It is possible to customise the background image and the image that is displayed in the centre of the Home page. The background image should be named vSEC_CMS_T_USS.exe-bgv.png and the image that is displayed in the centre of the Home page should be named vSEC_CMS_T_USS.exe-home.png. These image files need to be placed in the installation folder, normally located here: C:\Program Files\Versasec\vSEC_CMS Self-service.

The position of the background image and where this will be shown can be configured by setting the values below in a config file named vSEC_CMS_T_USS.exe-bgv.cfg. This file needs to be place in the installation folder, normally located here: C:\Program Files\Versasec\vSEC_CMS Self-service.

• * : 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.

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. 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 App 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 will give 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 a MHT file which 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 a 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 which 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.