Introduction
This article will describe how you can configure vSEC:CMS to support the lifecycle management of Thales IDPrime PIV credentials. The article will cover the following:
- Setup a template that will allow you to create and issue a Windows logon certificate to a Thales IDPrime PIV credential from vSEC:CMS console application;
- Issue a Windows logon certificate to the Thales IDPrime PIV credential;
- Log onto a Windows client using the issued Thales IDPrime PIV credential;
- Setup a template that will allow you to create and issue a Windows logon certificate to a Thales IDPrime PIV credential from vSEC:CMS User Self-Service (USS) application;
- Issue a Windows logon certificate to the Thales IDPrime PIV credential via USS;
- Log onto a Windows client using the issued Thales IDPrime PIV credential;
- Configure and demonstrate how to perform PIN unblock / reset using challenge-response.
This article will be divided into 2 sections depending on how you wish to manage the issuance of Thales IDPrime PIV credential: Issue Through vSEC:CMS Console or Issue Through USS.
The PKI used here will be a Microsoft Certificate Authority (CA). If another CA is to be used please refer to the Administration guide for details on configuring a connection to such a CA.
It will be required that at minimum you have already successfully completed the configuration steps described in the article Setup Evaluation Version of vSEC:CMS. The instructions in this document are applicable regardless of whether you are running the evaluation version or a production version.
Issue Through vSEC:CMS Console
If you will issue the Thales IDPrime PIV credential centrally by an operator then follow the instructions in this section.
Configure Smart Card Access
Typically the smart card access is already set to the correct type but for completeness we will cover this in the article.
From Options - Smart Card Access attach a Thales IDPrime PIV credential that you will manage with the vSEC:CMS. The vSEC:CMS will filter the card type and present the entry in the table.
Click the Edit button and for Smart Card Access make sure that Use native access if possible is selected and click Save to save and close.
If the table is empty when you attach the credential to filter for the card type then you should follow the instructions in the article Add Credential Configuration for details on how to add the correct template for the card type that you use.
Configure Data Export
This task is optional as normally you would not configure exporting the PUC code that can be used to unblock / reset the PIN code when the credential is locked. However if you do plan to extract the PUC code during the issuance then follow the instructions in this section to complete that task.
If you configure the PUC code to be exported during issuance then you will not be able to perform PIN unblock (either online or offline) operations.
Presuming that you plan to extract the PUC code to a file then it will be necessary to configure a data export template of type file in order to export the PUC code to a file.
From Options - Connections click the Configure button. Select Data Export and add this to the Selected pane and click Ok.
Click Data Export to open the configuration dialog. Click the Add button and enter a template name and for Target select File (export to file). Under File select Write automatically to file and for Filename enter location where the file is to be written to.
Click the Format button to configure the details that you want written to the file. In this example, it is important to select the variable ${Puc} as this will be the actual PUC code generated by the vSEC:CMS during the issuance. In this example, we will also write the users ID to the extract file.
Click Ok and Save to close and save the template.
Configure Challenge/Response For PIN Reset
The PIV standard only supports the resetting of the user PIN using a PUC code. Therefore, challenge-response is not normally supported for performing PIN resets. However, this is possible with vSEC:CMS.
From Options – Security in the Application Security section enable the Enable challenge/response for offline PUC based unblock.
Additionally, it will be necessary to enable support for this feature on the client side. The Enable challenge/response for offline PUC based unblock setting will need to be enabled in the vSEC:CMS User Self-service (USS) through the -configure option when configuring the setting on the USS.
See the Issue Credential section in Issue Through USS below where you will find instructions for installing the USS.
From a command prompt go to the location where the USS is installed and run the command: vSEC_CMS_T_USS.exe -configure
Then enable the setting Enable challenge/response for offline PUC based unblock as below. It should be noted that this setting can be enabled through GPO. See the article Configure Windows GPO for further details.
Additionally the Smart Card Access needs to be set to Use native access if possible.
Credential Configuration
1. From Templates - Card Templates click the Add button.
Click the Edit link beside General. Enter a template name and attach a Thales IDPrime PIV credential that is to be managed by this template and click the Detect button and wait for the vSEC:CMS to detect that it is a PIV token and click Ok.
Leave all other settings as default and click Ok to close and save.
2. Click the Edit link for Issue Card. Under User ID Options section enable Assign User ID and select the already configured AD connection.
In the Enroll Certificate Options section enable Enroll certificate(s) and click the Add button. Select the already configured CA connection from the Certificate authority drop-down list and select the smart card logon certificate template as configured on your CA from the Certificate template list. From the Card key container drop-down list select PIV Authentication.
Click Ok to save and close the dialog.
Accept all other defaults for the Issue Card dialog and click Ok to save and close.
3. If you intend to write the PUC code to file then follow the instructions here, otherwise you can skip this step.
Click the Edit link for Initiate Card.
Enable the System set PUC checkbox and click the Configure button. From the drop-down list select the data export file configured earlier in this article and click Add and click Ok and Ok to close.
Click Ok to save and close the template configuration.
The PUC code will be exported to the configured file the first time that a PIN is set on the Thales IDPrime PIV credential.
4. If it is required to perform signing of PIV objects during the issuance process then refer to the article PIV Settings for details on using this feature.
Issue Credential
From the Lifecycle page attach a blank Thales IDPrime PIV credential to your host.
Click the Issued oval and select the template from Select card template drop-down list and click Execute.
You will be prompted to enter your Operator passcode before the issuance will begin. Then you will be prompted to select the user from AD that the credential will be issued to. Select the user and at the end of the process you will get a short summary dialog of what operations were performed.
The credential will now show as Issued. The credential PIN by default will be blocked. You will need to set a PIN before you can use the credential. Click the Active oval followed by the Execute button. You will be prompted to authenticate again and then set a PIN that meets the policy supported on the credential. Once you complete this then the credential can be used to log onto your domain environment. Additionally if you have configured for the PUC to be exported to file then you should see the exported PUC in the file after this step.
Once you complete this then the credential can be used to log onto your domain environment.
Issue Through USS
If the end user will issue the Thales IDPrime PIV credential themselves via the USS then follow the instructions in this section.
Self-Service Connection
If you don’t have a connection for self-service already set up then from Options - Connections click the Add button and select User Self-Service and click Ok. Enable the enable SOAP checkbox. Depending on your environment settings enter a hostname and port to listen on. You can also setup support for SSL if you wish to use HTTPS for secure communication between the client and server. If you use SSL it is important that the HostIP address field is entered with the name of the server as it appears in the SSL certificate. The SSL certificate should be a machine certificate available on the vSEC:CMS server.
Make sure that the vSEC:CMS - User Self-Service service is running after you configure this in Windows services.
Configure Smart Card Access
Typically the smart card access is already set to the correct type but for completeness we will cover this in the article.
From Options - Smart Card Access attach a Thales IDPrime PIV credential that you will manage with the vSEC:CMS. The vSEC:CMS will filter the card type and present the entry in the table.
Click the Edit button and for Smart Card Access make sure that Use native access if possible is selected and click Save to save and close.
If the table is empty when you attach the credential to filter for the card type then you should follow the instructions in the article Add Credential Configuration for details on how to add the correct template for the card type that you use.
Configure Data Export
This task is optional as normally you would not configure exporting the PUC code that can be used to unblock / reset the PIN code when the credential is locked. However if you do plan to extract the PUC code during the issuance then follow the instructions in this section to complete that task.
Presuming that you plan to extract the PUC code to a file then it will be necessary to configure a data export template of type file in order to export the PUC code to a file.
From Options - Connections click the Configure button. Select Data Export and add this to the Selected pane and click Ok.
Click Data Export to open the configuration dialog. Click the Add button and enter a template name and for Target select File (export to file). Under File select Write automatically to file and for Filename enter location where the file is to be written to.
Click the Format button to configure the details that you want written to the file. In this example, it is important to select the variable ${Puc} as this will be the actual PUC code generated by the vSEC:CMS during the issuance. In this example, we will also write the users ID to the extract file.
Click Ok and Save to close and save the template.
Configure Challenge/Response For PIN Reset
The PIV standard only supports the resetting of the user PIN using a PUC code. Therefore, challenge-response is not normally supported for performing PIN resets. However, this is possible with vSEC:CMS.
From Options – Security in the Application Security section enable the Enable challenge/response for offline PUC based unblock.
Additionally, it will be necessary to enable support for this feature on the client side. The Enable challenge/response for offline PUC based unblock setting will need to be enabled in the vSEC:CMS User Self-service (USS) through the -configure option when configuring the setting on the USS.
See the Issue Credential section below where you will find instructions for installing the USS.
From a command prompt go to the location where the USS is installed and run the command: vSEC_CMS_T_USS.exe -configure
Then enable the setting Enable challenge/response for offline PUC based unblock as below. It should be noted that this setting can be enabled through GPO. See the article Configure Windows GPO for further details.
Additionally the Smart Card Access needs to be set to Use native access if possible.
Credential Configuration
1. From Templates - Card Templates click the Add button.
Click the Edit link beside General. Enter a template name and attach a Thales IDPrime PIV credential that is to be managed by this template and click the Detect button and wait for the vSEC:CMS to detect that it is a PIV token and click Ok.
2. Click the Manage button beside Self-service using the following template. Click the Add button. Enter a template name and enable Self-issuance enabled and Retire card enabled checkboxes. From the User Authentication for PIN Unblock drop-down list select Use windows credentials to authenticate user. Leave all other settings as is and click the Save button to save and close.
Click Close and from the main General dialog enable Self-service using the following template and from the drop-down list select the template just created. Leave all other settings as is and click Ok to save and close the dialog.
3. Click the Edit link beside Issue Card. Select the checkbox Automatically initiate cards after issuance and Issue by user(s) radio button. Click the Configure button in the User ID Options section. Select the AD connection already configured from User ID from drop down list and select Supplied domain credentials from Authenticate user using drop down list. Click Ok to save and close.
In the Enroll Certificate Options section enable Enroll certificate(s) and click the Add button. Select the already configured CA connection from the Certificate authority drop-down list and select the smart card logon certificate template as configured on your CA from the Certificate template list. From the Card key container drop-down list select PIV Authentication.
Click Ok to save and close the dialog.
Accept all other defaults for the Issue Card dialog and click Ok to save and close.
4. If you intend to write the PUC code to file then follow the instructions here, otherwise you can skip this step.
Click the Edit link for Initiate Card.
Enable the System set PUC checkbox and click the Configure button. From the drop-down list select the data export file configured earlier in this article and click Add and click Ok and Ok to close.
Click Ok to save and close the template configuration.
The PUC code will be exported to the configured file the first time that a PIN is set on the Thales IDPrime PIV credential.
5. If it is required to perform signing of PIV objects during the issuance process then refer to the article PIV Settings for details on using this feature.
Issue Credential
On a client machine it will be necessary to install the vSEC:CMS User Self-Service (USS) application. Use the vSEC:CMS Client MSI to install this component. It is recommended to install the USS silently as it is possible to pass in the URL link to the backend vSEC:CMS server that the USS needs to communicate with. This will remove the requirement to manually configure the USS to communicate with the backend in this case.
Open a command Window as administrator and change to location where the MSI installer is located. It is recommended to install the vSEC:CMS Credential Provider (CP) as this component will allow you to perform PIN reset / unblock from the Windows logon screen for both online and offline flow.
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS,CP USSSOAP="http://192.168.0.30:8443/uss"
Where USSSOAP points to the backend server where vSEC:CMS is installed. Important to append /uss to the end of the server hostname/IP. The communication between USS and server is HTTP(S) using SOAP protocol.
The client host will automatically reboot when running above command so make sure you have saved any material you may be working on when performing this task.
Start the My Smartcard from the shortcut icon on the client desktop. Go to the My Profile page. With the credential attached that is to be issued click the Issue button.
Enter the domain credentials of the user to authenticate.
At the end of the process you will be prompted to enter a PIN for the credential to complete the flow.
Once you complete this then the credential can be used to log onto your domain environment.
PIN Reset / Unblock
As already mentioned in this article the vSEC:CMS facilitates the resetting / unblocking of a Thales IDPrime PIV credential using challenge-response mechanism. This is a unique feature that vSEC:CMS provides as normally it is only possible to perform PIN reset / unblock using the PUC PIN.
Below we will provide 2 examples of how you can perform PIN reset / unblock where a user is online and a user is offline. A user is online when they are connected to the domain.
Example 1 - Online Reset / Unblock
A user has blocked their PIN and they need to unblock it. The user’s host is connected to the domain. If the vSEC:CMS CP is installed on the client then you can perform this from the logon screen.
From the CP select the credential that is to be used to logon where the PIN is blocked. Select the option Unblock PIN with vSEC:CMS USS.
From the reset / unblock dialog enter a new PIN and confirm and click the Unblock button to perform the reset.
You will be prompted to authenticate the user. In this case it will be the user’s domain credentials that they need to provide.
In the background the USS will communicate with the server to perform a challenge-response operation to reset the PIN. This will complete the reset / unblock flow.
Example 2 - Offline Reset / Unblock
A user has blocked their PIN and they need to unblock it. The user’s host is not connected to the domain. If the vSEC:CMS CP is installed on the client then you can perform this from the logon screen.
From the CP select the credential that is to be used to logon where the PIN is blocked. Select the option Unblock PIN with vSEC:CMS USS.
From the reset / unblock dialog click the Get button to generate a challenge code. This challenge code needs to be provided to an operator / help-desk person who will generate the Cryptogram (reset /unblock code) code and provide it back to the end user.
There is a one-to-one relationship between the challenge code and the generated cryptogram, therefore it is important that the credential is not removed during this process otherwise the challenge-response code will be invalidated.
The operator / help-desk person will generate the response code from Actions - Smart Card Unblock. Click the Search button and select the user whose credential is to be reset / unblocked.
Enter the challenge code into the Challenge field and click the Cryptogram button to generate the unblock code.
The reset / unblock code should then be provided back to the user.
Once the user has entered the cryptogram into the field provided they can enter a new PIN and confirm. Click the Unblock button to perform the reset. This will complete the reset / unblock flow.