2. ADCS#

2.1. Issue and Retrieve module parts#

The Retrieve part of the ADCS module is optional and has the purpose of retrieving machine certificates from the Windows server and import it into TrustView automatically, for the purpose of monitoring them.

You will find all the certificates imported this way, under the Other certificates in the left menu of TrustView.

The Issue part of the ADCS module allows you to issue internal certificates from one or more of your own CA’s, directly inside TrustView. See more details here.

2.2. TrustView ADCS Issue and Retrieve services#

Download the TrustView ADCS module package.

Note

If you do not have access to the ADCS module package, contact our Support to get access to the TrustView ADCS module package, with the newest release of the ADCS module and related files.

Install the PowerShell PKI module by opening PowerShell (may require admin rights) and running the following command:

Install the required PSPKI module#
1Install-Module -Name PSPKI

Tip

Go to PowerShell Gallery or GitHub to see the latest version of the PSPKI module and get installation instructions for the module.

Important

The minimum required version of the PSPKI module is v4.0.0.

Create a new directory or just copy the ADCS module package (including the content) to the following location on the TrustView server:

C:\Program Files\TrustView-ADCS

Note

The directory can be named anything and placed anywhere on the TrustView server, but avoid a temporary directory.

Create a service account for use with the ADCS module and assign the service account all permissions on the newly created TrustView-ADCS folder. The same service account can be used for both the Issue and the Retrieve service.

Adjust the trustview.properties file:

  • Generate a unique API key (without special characters) for the property file and use the same API key inside TrustView - (Settings ADCS settings)

  • Update trustviewnendpoint if TrustView is using a non-default port for localhost communication.

Important

If the ADCS related log files shows connection errors, you may need to use the HTTPS URL listed under the contextPrefix of the TrustView.groovy configuration file.

trustviewnendpoint property example#
1trustviewendpoint=https://trustview-url:8443/AdcsConnection/

Remember to remove port 8080 if using the HTTPS URL

Install the ADCS Issue and optionally the ADCS Retrieve services:

Install the Issue service of the ADCS module#
1C:\Program Files\TrustView-ADCS> .\TrustView-ADCS-Issue-Service.exe install
Install the Retrieve service of the ADCS module#
1C:\Program Files\TrustView-ADCS> .\TrustView-ADCS-Retrieve-Service.exe install

Important

The ADCS Retrieve service can be seen as optional and is only needed if you wish to retrieve certificates from your CA and import them automatically into TrustView to monitor them.

Configure the installed service:

  • Run the service as the service account with permissions assigned on the ADCS instance

  • Make sure the service startup type is set to Automatic

  • Start the service

2.3. Configuration of service account for ADCS integration#

The ADCS-frontend communicates with ADCS using a service account. This service account must be assigned the following permissions:

CA instance
Read
Issue and Manage Certificates
Request Certificates
All relevant issuance templates
Read
Enroll

Tip

You can choose or create any number of templates to assign the permissions to, but typically the Web Server template is used. Even if you assign the permissions to multiple templates, you will have the option to show or hide any number of them inside TrustView under the Settings menu.

2.4. Configuration of the trustview.properties file#

The file contains the following parameters that can be configured:

Adjust the API key and other properties as needed#
 1apikey=<api key>
 2trustviewendpoint=http://localhost:8080/AdcsConnection/
 3trustviewmonitoredcertsendpoint=http://localhost:8080/CertificateImport/
 4publicKeyString=foobar
 5_cahost=ica01.adtest.local
 6_caname=Adtest CA
 7
 8# Add a comma-separated list of templates to import
 9_templateImportList=WebServer, DomainWebServer
10
11# SSL validation options:
12#   default   = use system defaults (no override)
13#   pinnedcert = trust only certificate matching the public key (set the variable "publicKeyString")
14#   acceptall = trust all certificates (insecure)
15
16sslvalidationlevel=default

Note

The lines starting with the _ character (underscore) is commented out and therefore not used by default. Remove the _ to utilize the property.

By default, the ADCS module will attempt to retrieve all available templates and any CA’s it finds (you can see what specific CA’s are found in the log file, found in the logs directory, by setting the -loglevel to debug), but you can specify the CA and template you want to use (if necessary), when issuing ADCS certificates through API or TrustView by removing the _ character and changing the cahost, caname and templateImportList to fit your needs.

2.5. Setup certificate issuing from two or more separate CA’s#

To be able to issue ADCS certificates from two or more separate CA’s from TrustView, you must install the TrustView-ADCS-Issue-Service.exe for each CA, you wish to use and perform the steps above for the TrustView-ADCS directory, for each CA you wish to use. After that, each trustview.properties file in the respective TrustView-ADCS directory must contain the caname and cahost for the corresponding CA. templateImportList is optional for any of the CA’s.

Important

Each TrustView-ADCS-Issue-Service installed must be named something unique, as services with duplicate names cannot exist.

Example:

If ADCS certificates in TrustView must be able to be issued from two CA’s, the following setup could be used:

  • TrustView-ADCS1 (name of the directory containing the setup for the first CA)

  • TrustView-ADCS2 (name of the directory containing the setup for the second CA)

Open the TrustView-ADCS-Issue-Service.xml file in each TrustView-ADCS directory and change the name of the services:

1 <id>TrustViewAdcsIssueService1</id>
2 <name>TrustView ADCS Issue Service 1</name>

1 <id>TrustViewAdcsIssueService2</id>
2 <name>TrustView ADCS Issue Service 2</name>

Important

The ID must not contain any spaces, otherwise it would fail to install the service. Only the name can contain spaces.

After that, each TrustView ADCS Issue Service must be installed as normal (see step 7) and will then use the new designated names for the services. Adjust the caname and cahost in each trustview.properties file to match the CA that is used for issuing certificates.

Note

This can also be done with the TrustView-ADCS-Retrieve-Service, by following the same steps for the retrieve service.

2.6. Revoke ADCS certificates#

ADCS certificates can be revoked from inside TrustView by opening the detail page of the CA certificate you want to revoke and press Revoke certificate.

You can follow the status of the revocation by looking under the metadata or the event log on the detail page of the certificate.

Danger

A revocation of a ADCS certificate cannot be undone, once the action has been performed.

2.7. SSL Validation Options#

There are 3 options to choose from in the trustview.properties configuration file:

  • default = use system defaults (no override)

  • pinnedcert = trust only the certificate matching the public key (set the value of the variable publicKeyString)

  • acceptall = trust all certificates (insecure)

Note

The variable publicKeyString only needs to be changed if the pinnedcert option is chosen.

The variables trustviewendpoint and trustviewmonitoredcertsendpoint needs to be changed to the https version of your TrustView URL.

Example configuration#
1trustviewendpoint=https://trustview-url/AdcsConnection/
2trustviewmonitoredcertsendpoint=https://trustview-url/CertificateImport/

2.8. Troubleshooting#

If you have issues connecting with the auto-discovered or specified CA (this is controlled by the ADCS module property file), you can run the following PowerShell commands from the server, where the ADCS module is installed (this may not necessarily be on the TrustView server):

Ping a specific CA#
1certutil -ping "cahost.local\ca name"
View all information from the specific CA#
1certutil -view -config "cahost.local\ca name"
Fetch templates from CA#
1certutil -v -template

If you don’t know the name or host of the CA, there are several ways of getting that information - check the ADCS logs, look at the CA directly or use one of the following commands:

Commands for getting the CA config (each line is a separate command)#
1certutil -config - -ping
2certutil -getconfig

If you have a permission issue with any of the CA templates or one or more template is missing, run this command:

Fetch templates from CA#
1certutil -CATemplates

More utility commands can be found here.