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 importing them into TrustView automatically, for the purpose of monitoring them.

You will find all the certificates imported this way, under 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 CAs 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 trustviewendpoint if TrustView is using a non-default port for localhost communication.

Important

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

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

Once at least one ADCS connection has been set up, Settings shows a table per ADCS instance, per template, with two independent filters:

  • Import filter - whether certificates issued for that template should be imported into TrustView at all, and if so, whether they should start out as Active or Ignored.

  • Order filter - whether that template can be selected when ordering an ADCS certificate from inside TrustView.

Note

TrustView also has a separate, AD-based auto-filtering feature for ADCS-issued certificates, which automatically ignores machine certificates whose machine account has been decommissioned in Active Directory. See Auto-filtering of internally issued certificates under Settings.

2.4. What happens when a CA connection or template is disabled

As described under Select certificate issuer, a template is selected independently of which ADCS connection issues it. If the same template is advertised, with its Order filter enabled, by more than one enabled ADCS connection, disabling it on one connection - or disabling that connection entirely - has no effect on ordering: TrustView keeps issuing from whichever connection still advertises it.

If a template stops being orderable everywhere - its Order filter is off (or the template is gone) on every connection, or the only connection that had it is disabled - existing references to it are not automatically switched to another issuer or template. Instead, a daily job flags every recurring Automation Task, agent activation template and active agent connection that still points at it as having an outdated issuer, logs the change to its event log, and includes it in a weekly digest e-mail - see Outdated issuer notifications under Notifications. The flag clears automatically once the object is pointed at a different, orderable template or issuer, or if the original one becomes orderable again.

2.5. 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) are 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 CAs it finds (you can see what specific CAs 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.6. Set up certificate issuing from two or more separate CAs

To be able to issue ADCS certificates from two or more separate CAs 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 CAs.

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 CAs, 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 6) 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.7. Revoke ADCS certificates

ADCS certificates can be revoked from inside TrustView by opening the detail page of the certificate you want to revoke and pressing 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.

Note

Revoking a certificate does not need any separate connection or access - it is picked up and carried out by the same TrustView-ADCS-Issue-Service and service account already configured for issuing certificates (see Configuration of service account for ADCS integration above). The Issue and Manage Certificates CA permission already required there is what authorizes revocation as well, so no additional permissions need to be granted for this feature to work.

Danger

Revoking an ADCS certificate cannot be undone once the action has been performed.

2.8. 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 need to be changed to the https version of your TrustView URL.

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

2.9. 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
Verify the permissions for the CA
1certutil -config "cahost.local\ca name" -getreg CA\Security

More utility commands can be found here.