Legacy vSEC:CMS User Self-Service

Overview

Using the vSEC:CMS User Self-Service (USS) application it is possible for a user to manage their credential. From the USS 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.

USS 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

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

Configuration Client-Side

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

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

Settings

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

Check for card update on insert

In this section, it is possible to configure the behavior of the USS application 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 USS application will not perform any check on the user credential when attached;
• Select Check for PIN Change. The USS application 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 USS application 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 USS application 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 USS application will check to see if there are any updates pending that need to be performed on the credential such as certificate renewal.

Smart Card Reader

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 USS application.

Smart Card Access

From the Smart Card Access section, it is possible to configure how the USS 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 USS 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 USS 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 USS 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 USS application 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 USS 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 USS application 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 USS 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 Operator 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 USS application.

In order to configure any of the options available in the table above follow the instructions below. For example, if it is required to not allow users to delete certificates from the USS application then it will be necessary to perform the following steps:

1. Select the Action item My Certificates - Delete and click the Delete button.

2. Select the item deleted in the previous step and from the drop-down list select Hidden and click Add.

3. The item will now be listed in the main window and the Delete button will not be available from the My Certificates page of the USS application.

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 USS application 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 USS 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 USS 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 USS 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 USS 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 USS running in the system tray. It is possible to start USS in system tray mode by passing the parameter -s to the USS executable. For example, open a command prompt as administrator and go to the location where the USS is installed, typically C:\Program Files\Versasec\vSEC_CMS Self-service for 64-bit version and C:\Program Files (x86)\Versasec\vSEC_CMS Self-service for 32-bit version.

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 USS running in the system tray then you would need to add a shortcut to the USS executable vSEC_CMS_T_USS.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 USS 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 USS will auto connect.

The target should look like below if the USS is installed into the default location (for 64bit version):

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

Suppress Warnings at Startup

If the USS is configured to connect to the vSEC:CMS backend and for whatever reason the client is offline then when starting the USS a message dialog will be displayed warning the user that the USS 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 USS is installed, typically C:\Program Files (x86)\Versasec\vSEC_CMS Self-service.

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

Configure USS in Kiosk Mode

If it is required to configure the USS 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 USS executable file which is typically installed to C:\Program Files (x86)\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 USS should be run in kiosk mode. In order to run the USS in normal mode then change this value to 0x00000000.

Customise USS Layout

It is possible to change the default icon that appears in the top left of the main USS application dialog. By default, a vSEC:CMS icon will be shown.

Additionally, it is possible to change the splash screen image that is displayed when you launch the USS application. By default, NYC skyline will be shown.

In order to make these changes it will be necessary to include a file named cms_app.cfg and this should be placed beside the USS executable file which is typically installed to C:\Program Files (x86)\Versasec\vSEC_CMS S-Series if you have installed the 32-bit version or C:\Program Files\Versasec\vSEC_CMS S-Series if you have installed the 64-bit version.

The contents of the file would be as below (if 64-bit version is installed into default location):

Where signature value should be: KXpC+EQaYM+DSqPx+ur6dycgzQgq3xL1BdBGmaI89+8UTNvVY1rCL73F+bSdsI11XVJlBuwRHjhKFhpeNzcSIO7oykRyqJ/7DB/8YZ5rD7o/+p0uXNxzMpY6Va6I5WTUjaiw8KeZJ6uQ10ye4VIuJ2fi8LBr/2WUZ+l39O5zW8k=

The element <gui> needs to have <logo> and <startimg> elements. Inside these elements a <file> element will point to the location where these images will reside.

For the <logo> image the file needs to be of type BMP or PNG and have a size of 220 x 40 pixels.

For the <startimg> image the file needs to be of type BMP or PNG and have a size of 1012 x 637 pixels.

Configure USS Server-Side

If USS 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 USS 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 USS client then enable Self-issuance enabled. Additionally, if it is required that the end user will be allowed to retire their credential from the USS client then enable the Retire card enabled checkbox. These functions will be performed from the My Profile page in the USS application.

In the User Authentication for PIN Unblock section 3 options are available from the drop-down list, Use passphrase to authenticate user, Use windows credentials to authenticate user and Use smartcard challenge/response.

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 USS application is required to enter a passphrase to authenticate during the unblock procedure.

Enable the System generates passphrase at card issuance if the vSEC:CMS application should generate a passphrase for the user when issuing the user's credential.

Enable the User may change passphrase checkbox if the user is allowed to change their passphrase from the USS application.

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