Before beginning this article, it is necessary that you have successfully completed the article Install and Configure vSEC:CMS on First Use.
Follow the instructions in this section to setup and configure the vSEC:CMS such that it will be possible to issue and manage smart card tokens using the vSEC:CMS User Self-Service (USS) application. After completing this configuration, it will be possible to issue a blank smart card token with a smart card logon certificate, perform smart card PIN unblock and perform certificate renewal from the USS application.
Note: The PKI used in this example use case will be an MS CA.
Note: The smart card type that will be managed in this use case will be a generic mini-driver smart card token.
Step 1 - Setup Encrypted Key Store
In order to use USS, it will be necessary to install an Operator Service Key Store (OSKS) in the vSEC:CMS.
Follow the instructions in the article Create Operator Keystore for details on how to setup OSKS.
Step 2 - Create Windows Account
By default, the vSEC:CMS is configured to run under the Windows SYSTEM account. In this type of configuration, it is required to create a dedicated Windows account for the vSEC:CMS service. This account should only be used for the vSEC:CMS service.
The Windows account does not need to be a specific type; therefore, domain user type is sufficient but you will need to configure specific permissions for this account as described below in the section Configure Windows Permissions.
Important: It is recommended to configure the Windows account password to never expire. If the dedicated Windows account password is not configured to never expire then the vSEC:CMS service will fail to start if the Windows password is changed.
Configure vSEC:CMS Service
1. Once a dedicated Windows account is created open up Windows service, services.msc, and stop the service vSEC:CMS Service.
2. Right click the service vSEC:CMS Service and select Properties.
3. Go to the Log On tab and select This account radio button. Manually enter the Windows user account name created in Step 1.
Important: The Windows account name should be entered in the Windows account format pre-2000. For example, if the Windows account name is cms_service and the domain name is VERSATILESECURI, therefore the account name should be entered as: VERSATILESECURI\csm_service. If the account name is not entered in this format the CMS service may not start automatically after a server restart.
Configure Windows Permissions
It will be required to give full control to the dat folder of the vSEC:CMS for the Windows user account. The dat folder will typically be located in the location where the vSEC:CMS was installed, typically C:\Program Files (x86)\Versasec\vSEC_CMS vSEC:CMS if the default location was chosen during installation.
1. Right click the dat folder and select Properties.
2. Go to the Security tab and click the Edit button and add the specific Windows user account created. Give the user full control and click Apply.
3. Additionally, it will be necessary to configure specific permissions to a registry folder for this Windows account. Open registry editor using regedit and browse to below location:
Right click on the Service folder and select Permissions. Click the Add button and add the Windows user created and give them full control. Click Apply and close.
4. Start the vSEC:CMS Service from the Windows service. Now the S-Service service will run under the dedicated Windows account.
Important: If the vSEC:CMS does not startup and shows an error that the database specified does not exist this is typically because the Windows user account cannot access the dat folder and/or cannot write/execute in the dat folder. Make sure that the Windows user account can access and read/write/execute in this folder.
Additionally, check that the registry key below is set to a value of 0:
Important: If the vSEC:CMS is configured to use MS SQL as the database it will be required to add the dedicated Windows user account to the MS SQL database.
Important: If the vSEC:CMS is configured to use MS CA it is required that the dedicated Windows account has permissions on the CA to revoke certificates. For example, in the Windows certsrv console right click the CA and select Properties. Then from the Security tab ensure that the dedicated Windows user account is in a Group or user list with minimum permission of Issue and Manage Certificates.
Additionally, if using MS CA and certificate operations, such as issue or revoke, are being performed from the USS, then in this case the USS will perform operations on the CA using the dedicated Windows account. The CMS service will connect to the CA remotely in this case, therefore it is important that the correct Interface Flags, as defined in MS Certificate Services Remote Administration Protocol are set. This flag is configured on the CA server in the registry key:
It is expected that a skilled MS Certificate Services integration engineer would be performing this check and configuration if it is required to be configured. Otherwise if this flag is not configured correctly you may get a warning from the USS application stating “The certificate cannot be revoked automatically as the Certification Authority (CA) is currently unreachable. The revocation request will be cached and will be sent to the CA when the CA is available.”
Additional Important Information
1. From the Operator console, when issuing/re-issuing smart cards with certificates from the Lifecycle or Actions – Certificate(s)/keys page, the vSEC:CMS uses the current Windows logged on user if the CA connection is configured to Use from domain. Therefore, this user needs to have Enroll permissions on the CA certificate template. Otherwise the vSEC:CMS will use the credentials that have been configured from the CA connection when opening the Select CA dialog from the CA connector.
2. From the Operator console when a smart card is being revoked the vSEC:CMS uses the current Windows logged on user if the CA connection is configured to Use from domain. Therefore, this user needs to have Issue and Manage Certificates permissions on the CA, which are configurable from the certsrv console on the CA. Otherwise the vSEC:CMS will use the credentials that have been configured from the CA connection when opening the Select CA dialog from the CA connector.
Step 3 - Configure Request Signing Settings
It will be necessary to configure an Enrollment Agent (EA) certificate that the vSEC:CMS will need access to when issuing and renewing user certificates from the USS. An EA certificate can be created using the Windows built in MMC functionality. Follow the instructions below to setup an EA certificate.
Important: In order to issue an EA for the dedicated Windows account you have 2 options:
1. Log onto the CMS server with the dedicated account and follow the steps below.
2. On the CMS server use the Windows runas command to launch MMC. The command should be: runas /user:user@domain "cmd /c mmc %windir%\system32\certmgr.msc"
Note: The dedicated Windows account will need logon permissions in either of these cases. You can give the dedicated Windows account temporary Domain Admins to complete this step. Once complete with this step you can remove the user from the Domain Admins.
1. Start MMC.
2. From File - Add/Remove Snap-in select Certificates and click the Add button.
3. Select My user account and click Finish and click Ok.
4. Right click Certificates under Personal and select All Tasks - Request New Certificates to start the EA certificate issuance wizard.
5. Click Next
6. Click Next
7. Select the Enrollment Agent template available on the CA and click Enroll
8. The EA will now be issued for the dedicated Windows user.
Important: You should now log off the server as the dedicated logged on service account.
Important: It will be necessary that a CA template of type EA is available to complete the steps above. If there is no EA template available then contact your CA administrator in order to set one up. The EA template configured on the CA will need to have disabled the authorized signatures required from the Issuance Requirements tab.
9. Log into the vSEC:CMS console and from the Options - Operators page click the Cert request signing button.
10. Select the CA to be used from the Certification Authorities drop down list.
11. From the Certificate(s) drop down list select the EA certificate that will be used. The vSEC:CMS will present the certificate(s) it finds from the Windows certificate store for the Windows user account that the vSEC:CMS service is running under. If an HSM is used to store the private key for the EA then the HSM will need to support MS-CAPI/CNG.
Step 4 - Setup USS Connection
1. From Options - Connections click the Configure button. Select User Self-Service and click right arrow button to add it to selected connectors and click Ok.
2. Click the User Self-Service frame added to open up the configuration dialog.
3. Enter the host name of the vSEC:CMS server in the field below All adapters and the port that the server will listen on.
4. The setting Enable get service metadata is enabled and cannot be configured from this dialog. It is shown for information purpose. This is a WSDL web services scheme to tell potential clients about the structure of the web service.
5. Optionally, enable the Use SSL checkbox if it is required to use communication over SSL/TLS.
6. If the clients on which the USS is installed are configured to go through a HTTP proxy then in the Server connection point section enable the Customized endpoint address and enter the URL of the end point, i.e. the URL that should be configured on the end user's client workstation.
7. If SSL/TLS is used then from the Server certificate select the server certificate to use for the SSL/TLS. This certificate needs to be available in the MS certificate store for the local machine in the Personal store.
8. Click Ok to save the configuration. Additionally, make sure the Windows service vSEC:CMS User Self Service is running and that the local firewall has a rule for the port number configured to allow HTTP traffic.
Step 5 - Setup USS Card Template
1. Navigate to Options - Smart Cards page. When the page is loaded attach the smart card token that is to be issued with the vSEC:CMS. The vSEC:CMS will filter the card type and present the smart card template available in the vSEC:CMS.
2. Select the entry and click Edit. ForSmart Card Access ensure that Use minidriver if possible is selected and click Save.
3. From Templates - Card Templates click the Add button.
4. Click the Edit link for General.
5. Enter a template name and attach the smart card token that is to be issued and click the Detect button to allow the vSEC:CMS to detect the smart card token type that is to be used for this card template.
6. Click the Manage button to configure the USS template. Click the Add button. Enter a template name. In the Issuance section enable the Self-issuance enabled and Retire card enabled check boxes. In the User Authentication for PIN Unblock section enable the Use windows credentials to authenticate user check box. In the PIN Unblock Codes section leave all settings as is. Click the Save button to save and close the dialog and navigate back to the General dialog.
7. From the General dialog select the Self-service using the following checkbox and select the USS template from the drop-down list created in the previous step.
8. Leave all other default settings in the General dialog and click Ok to save the settings and close this dialog.
9. Click the Edit link for Issue Card.
10. From General Options enable the Automatically initiate cards after issuance check box and select the Issue by User(s) radio button.
11. Click the Configure button and select the AD already configured from the User ID from drop down list. For Authenticate user using drop down list select Supplied domain credentials (note: in versions prior to 5.1.0 this was named Windows domain credentials) and click Ok to save and close the dialog.
Alternatively, from the Authenticate user using drop down list you can select the option Current logged on windows credentials. If this option is selected then during the self-service issuance the current logged on Windows credential will be used for the smart card issuance. In this case the end user will not be requested to enter an authentication credential. It is therefore strongly recommended to make sure that the smart card PIN is blocked at the end of the issuance flow. Then the user should go through an unblock PIN flow thereby to ensure the user performs a secondary authentication step. In order to disable the setting of a PIN at the end of the issuance flow you should disable the Automatically initiate cards after issuance check box in the General Options section.
Important: The AD connection used here needs to be configured from Options - Connections to use current user credentials. From the AD connection dialog ensure that the checkbox Use current user credentials is checked.
12. From Enroll Certificate Options section enable Enroll certificate(s) and click the Add button. Select the CA already configured 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 and click Ok to save and close the dialog.
13. Leave all other default settings for the Issue Card dialog and click Ok to save and close.
Important: It is important that the Windows smart card logon certificate template on the CA is configured to require an authorized signature. From the Issuance Requirements tab for the certificate template properties on the CA make sure to enable This number of authorized signatures and set a value of 1 and for Application policy drop down list select the Certificate Request Agent option.
Step 6 - Setup USS Application
On the client device connected to your domain it will be necessary to install the USS application. The USS application will need to be configured to connect to the vSEC:CMS application in order to perform self-service functions. The USS application uses TCP/IP as the communication protocol; therefore, a URL will need to be configured on the USS application. This URL can be passed in as a parameter to the USS installer.
The parameter is: /url="https://my_sedition_server/uss".
Note: https or http should be used for the URL depending on whether SSL/TLS is configured on the vSEC:CMS connection configuration for USS.
For example, from a command window start the installer as:
If you wish to install the USS in silent mode you can perform this with the /S parameter passed from a command line. The /S is case sensitive:
C:\vSEC_CMS_T_USS.exe /url="https://cmsdemo.versasec.com:8443/uss" /S
Important: It is required to have English installed as Region and Language settings on the host where the USS application is to be installed, i.e. English needs to be installed but does not need to be set as the default language on the client.
Additionally, if you do not pass in the URL from command prompt it is possible to configure the URL post installation. Follow the instructions below to configure the URL.
1. From a command dialog start the USS application configuration dialog to configure the vSEC:CMS. For example, if the USS application is installed on a Windows 64-bit OS and is installed in the default location then run the command: vSEC_CMS_T_USS.exe -configure from the root installation of the USS.
2. Go to the Server tab and enter the full URL for the vSEC:CMS as configured in Setup USS Connection above. Click the Test button to ensure connectivity. If the communication is successful a success dialog should appear. Click the Close button to save and close the dialog.
Step 7 - Issue Smart Card from USS Application
1. On the client host start the USS application from the My Smartcard shortcut icon on the desktop.
2. Click the My Profile link and with a blank smart card attached click the Issue button to begin the issuance process.
3. From the drop-down list in reader, make sure to select the correct card reader that the smart card token is inserted in. Select the template in the card template drop-down list as configured above and click the Issue button.
4. Enter the Windows domain user name and password to authenticate and click Ok.
5. The issuance process will now perform a number of operations. Once complete the user will be prompted to set a PIN code on the smart card token. Enter a PIN that meets the PIN policy requirements and click the Initiate button to complete the issuance.
6. This completes the issuance flow.
Step 8 - Perform Online PIN Unblock from USS Application
1. If it is required to perform a PIN unblock from the USS application go to the My PIN page and select the Unblock PIN (Crypto) radio button. Enter a new PIN code that meets the PIN policy requirements and confirm this value. Click the Unblock button to proceed.
2. Enter the Windows domain user name and password to authenticate and click Ok. In the background, a challenge-response will be performed with the vSEC:CMS to complete the unblock. Once complete a success dialog will appear.
3. This completes the online PIN unblock.
Step 9 - Perform Certificate Renewal from USS Application
1. If it is required to perform a certificate renewal from the USS application go to the My Certificates page and select the certificate from the list of available certificates and click the Reissue button.
2. Enter the smart card token PIN to authenticate and complete the certificate renewal.
3. This completes the certificate renewal.