Introduction
From version 6.0 it is possible to configure the connection to Entrust CA Gateway to manage the certificate lifecycle with any credential that is supported by vSEC:CMS. The Entrust CA Gateway API is a RESTful Web service API that provides a range of certificate issuance and management functions.
This article will describe how you can set up a connection to Entrust CA Gateway and then use this connection to issue and manage the lifecycle of a certificate on a credential managed by vSEC:CMS. The following will be performed in this article:
- Setup a CA connection template to Entrust CA Gateway;
- Create a credential template and issue it via the vSEC:CMS operator console with an S/MIME certificate issued from Entrust CA Gateway;
- Create a credential template and issue it via the vSEC:CMS self-service with an S/MIME certificate issued from Entrust CA Gateway.
It will be required that you have completed, at a minimum, 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.
Configure Connection
The first requirement is to set up a connection to your Entrust CA Gateway. Navigate to Options - Connections - Certificate Authorities and click Add. Enter a template name and in the drop-down field select Entrust Gateway. In the Entrust Gateway Server URL enter the appropriate connection URL for your setup. You will need to have a client certificate for the connection. This can be installed in the local Microsoft certificate store for the Windows account that vSEC:CMS service is running under.
It is recommended that the client certificate used here is installed into the local Microsoft certificate store before configuring the connection. For example, in this example the certificate is stored as below where the Current User is the Windows user that vSEC:CMS service is running under.
Click the Test button to test that the details are correct and that you can connect ok. If all the details are correct you should get a success dialog.
Click the Get Instances which will retrieve all available CAs. Select the CA that you wish to use from the available ones in the drop-down field.
Click the Templates button. Select Show all and click Update. You should see a list of all the available templates. Click Ok to close out.
Click the Request fields button. Here you configure how the certificate request fields will be populated depending on what you need to be set in the certificate request fields.
Click the Fields button and from the Available list select the certificate request fields that you wish to use. In this example we will use DN - Common Name and add this to the Selected list on the right hand side and click Ok.
We need to configure how the certificate request field gets populated with data. Click the Value field in the area as shown below.
This will popup a dialog like below. There are 2 ways that you can populate data into the request field. If you have vSEC:CMS variables already configured to map to Active Directory attributes (see the article Using Variables for details) then you can select Use variable and select the variable that you want to use or add one by clicking Add variable. Alternatively, select Use free text and enter the static data, Bob Smith in this example and select Ok to save and close.
Click Ok to save and close.
You can enable the Proxy through server (recommended) if you plan to issue credentials through self-service or client operator consoles. Click Save to save and close the connection settings.
Issue Credential via Operator Console
In this section we will describe how you can configure a credential template that can then be used to issue a certificate from an Entrust CA Gateway to a supported hardware credential. The issuance workflow in this case would be done centrally by an operator/issuance officer.
Navigate to Template - Card Templates and click Add. Select General[Edit]. Enter a template name and for Card type select Minidriver (Generic minidriver card). Leave all other settings as default and scroll to the bottom of the dialog and select Ok to save and close.
Select Issue Card [Edit]. Presuming that a connection is already in place to connect to a directory (Active Directory) in the User ID Options section select Assign user ID and select the AD connection from the drop-down list.
In the Enroll Certificate Options sectionenable Enrol certificate(s) and click Add. Select the CA from Certificate Authority drop-down field and select the certificate that we will issue during the card issuance. Click Ok to save and close.
Leave all other settings as is.
Scroll down to the bottom of the dialog and click Ok.
Click Ok to save and close the template configuration.
Navigate to the Lifecycle page. Attach a blank credential and click the Issue oval. Select the template from the drop-down field and click Execute.
This will start the issuance flow. You will be prompted to select the user from AD that the credential will be issued to. In this case we will select a user Bob Smith from our example AD. This user’s CN will match the static value we entered when setting up the CA connection earlier.
The keys will be generated on the credential and the certificate request will be created and sent to the CA for verification and issuance. Once issued by the CA it will send back to the credential and store it there. A short summary will be provided on completing the issuance.
The credential PIN by default will be blocked. You will need to set a PIN before you can use the certificate on 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 the certificate can be accessed and used as needed.
Issue Credentials via Self-Service
In this section, we will describe how you can configure a credential template that can then be used to issue a certificate from an Entrust CA Gateway to a supported hardware credential. The issuance workflow in this case would be done by the end-user using vSEC:CMS User Self-Service (USS) application.
If you don’t have a connection for self-service already set up then from Options - Connections click the Add button, select User Self-Service, and click Ok. Enable the Enable gRPC checkbox as we will use gRPC for this article.
Please ensure that you have read through the article vSEC:CMS Client-Server Communication which gives more details on vSEC:CMS client-server architecture.
Depending on your environment settings enter a hostname and port to listen on. You can also set support for SSL if you wish to use HTTPS for secure communication between the client and server. If you use SSL the HostIP address field must be 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.
Ensure that a credential configuration exists for the credential that you are going to use here. See the article Add Credential Configuration before starting below.
From Templates - Card Templates click the Add button.
Click the Edit link beside General. Enter a template name. Presuming that you are using one of the minidriver credentials that is supported by vSEC:CMS select Minidriver (Generic minidriver card) for Card type.
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.
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 sectionenable Enrol certificate(s) and click Add. Select the CA from Certificate Authority drop-down field and select the certificate that we will issue during the card issuance. Click Ok to save and close.
Leave all other settings as is.
Scroll down to the bottom of the dialog and click Ok.
Click Ok to save and close the template configuration.
On a client machine it will be necessary to install the 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 the location where the MSI installer is located. Run the command similar to below
msiexec /i "vSEC_CMS Client 64bit.msi" /quiet ADDLOCAL=USS USSGRPC="https://2016-server:8445" USSPCL=4
Where USSGRPC points to the backend gPRC service where vSEC:CMS is installed and USSPCL=4 configures the USS client to use gRPC.
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.
Depending on the credential that you are testing with it will be necessary to have the appropriate credential drivers installed on your host. Please check with the credential provider that you have the correct credential drivers installed.
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 the certificate credential can be used for whatever use cases are required.