1. Automation¶

Important

Using TrustView for automation requires a license for the TrustView Automation module. Contact Support or Sales for more information.

TrustView allows you to automate deployment of SSL/TLS and other certificates on servers and other devices, such as load balancers and firewalls. Automation is supported using several different approaches:

Automation tasks

ACME and SCEP clients

Native Citrix NetScaler integration

Native Azure integration

ACME (Automatic Certificate Management Environment) is a protocol for automated certificate management. This includes issuance, renewal and deployment of certificates. TrustView offers an ACME server and, therefore, allows any ACME client to issue and renew certificates using TrustView.

SCEP (Simple Certificate Enrollment Protocol) is described by the informational RFC 8894. Older versions of this protocol became a de facto industrial standard for pragmatic provisioning of digital certificates, mostly for network equipment. The protocol has been designed to make the request and issuing of digital certificates as simple as possible for any standard network user. These processes have usually required intensive input from network administrators, and so have not been suited to large-scale deployments.

1.1. Automation tasks¶

Besides using an external ACME or SCEP client, or the native Citrix NetScaler/Azure integrations described below, TrustView has its own native automation mechanism for issuing, renewing and deploying certificates on a recurring schedule, without an external client. An Automation task combines three independently chosen parts:

A certificate producer - where the certificate comes from: ADCS, Let’s Encrypt, a certificate ordered through the Cryptomathic backend (Certum, DigiCert, GeoTrust), or a local issuer.
A key container - where the private key is generated or supplied: generated by TrustView itself, an Azure Key Vault, a Citrix NetScaler key pair, or an externally supplied CSR.
A deployment - what happens with the resulting certificate: deployed to an Azure Key Vault, deployed to a Citrix NetScaler, installed on TrustView’s own Tomcat, or delivered by e-mail or a self-service webpage link (see self-service pages in Certificate Checkout for how that link behaves).

To create one, go to Automation tasks and click Add, then choose the producer, key container and deployment for the task. Once created, an Automation task runs on its own schedule and can be started immediately with Start now, in addition to Activate, Disable and Ignore.

A background job checks every 5 minutes for any active task whose Next run date has passed. That Next run field - a date, shown both on the task’s page and in the task list - can be set to any future date to control exactly when the task first starts. Once a cycle finishes successfully, the task reschedules itself automatically: Next run is set to 35 days before the newly issued certificate’s expiry, a fixed interval that is not user-configurable. While a cycle is in progress, its next step is checked every 60 seconds; a failed step retries with a growing delay, and after 4 failures the task moves to an error state that needs to be reset before it will run again.

An Automation task can also be created as a one-time Certificate order instead of a recurring task. A one-time order is not issued automatically - it first appears in its own pending list and must be approved by a user with certificate-order-approval permission (in addition to automation-write permission) before TrustView proceeds with it.

Tip

A custom ACME issuer registered under Settings (in addition to the built-in ADCS, Let’s Encrypt and backend-issued options) can also be selected wherever an issuer is chosen, including in activation templates further down this page.

1.2. Automation using ACME clients¶

To get an overview of the most common ACME clients available, check here: ACME clients overview.

Setting up an automated certificate issuance and renewal process using an ACME client and TrustView requires the following steps:

Installing an ACME client on a server (e.g. simple-acme or Certbot)

Initial execution of the ACME client with TrustView configured as the ACME server

Approval of the ACME client as an automation agent in TrustView

Configuring the ACME client to run at regular intervals (only necessary in certain cases)

Important

Note that to issue Let’s Encrypt certificates, you need to configure the DNS integration from TrustView for full automation. See DNS integration for details.

To issue Certum, DigiCert or GeoTrust certificates (external certificates) the domain(s) must be prevalidated for the OV and/or EV type (depending on your needs). For DV, the DNS integration must be configured since it needs to be validated on a per-domain basis.

In the following guide and examples, we show, step by step, the required tasks for setting up a certificate for automated renewal and deployment with the following ACME clients:

simple-acme (Windows)

Certbot (Unix - e.g. Linux and macOS)

Note

simple-acme is a backwards-compatible, drop-in replacement for win-acme. See the project history here. Both ACME clients can be used, but consider that simple-acme is newer and actively maintained.

Important

If you have already purchased a certificate through TrustView and wish to reuse it for an automation agent, you must ensure that the common name (CN) and SANs for the automation agent match the already issued certificate exactly, for TrustView to be able to reissue it. If it does not match, it will count as a new certificate that the automation agent will attempt to issue.

1.3. Hostnames and IPs used during automation¶

There may be cases where your network is closed, and you only want to open for the necessary inbound and outbound connections. The following is needed to perform automation with TrustView:

Inbound to TrustView:

From the servers running your ACME and/or SCEP clients - port 443. TrustView acts as the ACME/SCEP server, so these clients initiate the connection - with one exception, see ACME challenge checking below.

Outbound from TrustView:

Connect outbound to api.trustskills.com - port 443 - used for backend-brokered certificate orders (this is how Certum, DigiCert and GeoTrust certificates are actually issued - TrustView places the order through this backend rather than contacting those CAs directly)

Connect outbound to view.trustskills.com - port 443 - used for a cloud-reachability check

Let’s Encrypt’s own ACME endpoint - port 443 - only needed if the Let’s Encrypt issuer is used

Your configured DNS provider’s API - port 443 - only needed if DNS-01 validation is configured for automation (the hostname depends on the provider, for example api.cloudflare.com, api.dnsimple.com or rest-api.eurodns.com)

Outbound port 80 to the domain being validated, and/or outbound DNS access - only needed if ACME challenge checking is enabled (it is disabled by default)

This also applies for automation with Citrix NetScaler, which additionally requires outbound SSH/SFTP access on port 22 to the NetScaler, for certificate upload.

For automation with Azure, TrustView also needs outbound access to management.azure.com, your Key Vault’s *.vault.azure.net hostname, login.microsoftonline.com and graph.microsoft.com - all on port 443.

1.4. ACME challenge checking¶

By default, when TrustView’s ACME server issues a certificate to a connected client, it relies on how that client was approved as an automation agent (matching IP subnets/hostname patterns, or manual activation) and does not independently re-verify that the client actually controls the requested domain(s).

Challenge checking is an optional setting that turns this independent verification on. When enabled, TrustView performs the ACME challenge validation itself, before considering an order valid:

For a HTTP-01 challenge, TrustView makes an outbound HTTP request to http://<requested domain>/.well-known/acme-challenge/<token> (port 80) and compares the response to the expected value.

For a DNS-01 challenge, TrustView looks up the _acme-challenge.<requested domain> DNS TXT record.

Important

Challenge checking is disabled by default. With it left off, TrustView makes no such connection and the ACME/SCEP automation flow is inbound-to-TrustView only, as described above. Enabling it adds the outbound connection listed under Hostnames and IPs used during automation.

Challenge checking can be configured in two places:

As the default for new automation agents: go to Agents Agent client info, click the relevant ACME Directory Resource URI, and check or uncheck Challenge checking enabled by default.

Per automation agent, overriding the default: on the automation agent’s own detail page (see Automation agent activation), check or uncheck Challenge checking.

Note

Challenge checking behaves identically regardless of certificate issuer, including for an ADCS certificate - there’s no special case for ADCS in this check. This is separate from the CA-imposed domain-validation requirements described earlier on this page for the external issuers (prevalidation for Certum/DigiCert/GeoTrust, DNS integration for Let’s Encrypt) - since an ADCS certificate comes from a CA under your own organization’s control, there’s no external domain-ownership requirement to satisfy in the first place, so leaving Challenge checking off (the default) for an ADCS agent means no domain validation happens at all, by design.

The ACME protocol itself still requires a challenge/response step for every order regardless of issuer, so an ACME client will still request and complete an HTTP-01 or DNS-01 challenge even when the certificate being issued is an ADCS one. Whether TrustView actually checks that response depends solely on the Challenge checking setting above, never on which issuer is selected.

SCEP has no equivalent challenge/validation step at all - agent approval (IP subnet/hostname matching, or manual activation) is the only check performed there.

1.5. simple-acme and Certbot logs¶

For simple-acme, the logs can be located by default here:

C:\ProgramData\simple-acme

It is also possible to set up custom logging for simple-acme, see simple-acme custom logging.

For Certbot, the logs can be located by default here:

/var/log/letsencrypt/

1.6. Customize the ACME URL directory path¶

It is possible to customize the directory path for the ACME URL, when using TrustView as an ACME server. This can be done by adding the following line to the TrustView.groovy configuration file.

Using HTTPS¶

acmeContextPrefix = "https://acme.example.org"

Using HTTP¶

acmeContextPrefix = "http://acme.example.org"

After the line has been added or adjusted as needed, save the file and restart the TrustView service or reload the configuration from the Settings menu, for it to take effect.

1.7. Tune the ACME server’s own behavior¶

TrustView’s ACME server has a few properties of its own that can be adjusted in the TrustView.groovy configuration file, separately from anything an individual ACME client controls:

acmeClientsOrderRateLimit - the maximum number of orders a single ACME client can have in flight at once. Defaults to 10.
acmeIssuingTimeout - how long (in seconds) an order is allowed to sit pending before TrustView considers it stuck and times it out. Defaults to 300 (5 minutes).
acmeDefaultRenewalDaysBeforeExpiry - the server-side default renewal window, in days before expiry. Defaults to 30. Most ACME clients (such as simple-acme, see “Change the renewal interval for simple-acme” below) set their own renewal window independently of this.
letsEncryptAutomatedOrderProcessingEnabled - whether TrustView’s background job automatically completes pending Let’s Encrypt orders (validation and finalization) as part of its regular processing. Defaults to true. Setting it to false leaves pending Let’s Encrypt orders unprocessed - only disable it temporarily, for troubleshooting.

Example - in TrustView.groovy¶

 acmeClientsOrderRateLimit = 20
 acmeIssuingTimeout = 600
 acmeDefaultRenewalDaysBeforeExpiry = 45
 letsEncryptAutomatedOrderProcessingEnabled = false

After adding or adjusting any of these, save the file and restart the TrustView service or reload the configuration from the Settings menu, for it to take effect.

1.8. Automation examples¶

1. Set up automation with simple-acme and IIS website

Step 1a

Install and configure simple-acme

Start by downloading simple-acme and unpack it in a directory, on the Windows server you want to automate certificate renewal on. As long as the simple-acme folder is not zipped or archived, the location is not important.

Tip

Even though simple-acme can be run from anywhere on the server, it is still recommended to place the simple-acme directory in a location that does not get deleted or removed (for example, not in a temp folder).

e.g. "C:\Program Files\simple-acme"

Next, one additional step is required to allow simple-acme to use TrustView as an ACME server.

Update the RetryCount line in the settings.json file with the following:

"RetryCount": 150

The default value is 15, but changing this value will allow the simple-acme agent to retry and begin the automation after the agent has been activated in TrustView. This means you can get the automation to run, by executing one single PowerShell command.

Important

This method will not work with wildcard SSL certificates. If using a wildcard certificate such as *.example.org then you must change the PreValidateDns from True to False, in the Settings.json file from simple-acme, because external CAs such as Certum and DigiCert will no longer allow wildcard SSL certificates to be validated through an HTTP-01 challenge.

Step 1b

Configure DNS validation method (Wildcard certificates)

If using a wildcard certificate when automating, you need to use the DNS validation method, as it’s not possible to use the HTTP validation method.

Note

If you are not using a wildcard certificate, this step is not necessary, and you can continue using the HTTP validation method (–validationmode http-01) in the simple-acme command.

Start by creating a PowerShell script containing the following:

exit 0

Name it dnsvalidationscript.ps1 (or something else) and place it in a temp folder on the C: drive of the server where simple-acme is placed, or in any other directory, as long as you remember to adjust the script path in the command.

Step 2a

Initial run of simple-acme without wildcard certificate

Execute simple-acme for the first time without using a wildcard certificate. You must replace {{acme-directory-url}} to match your configuration. You can find the {{acme-directory-url}} here; it can also be found inside TrustView, under the Automation Task menu section.

simple-acme command to run if you are not using a wildcard certificate¶

.\wacs.exe --baseuri "{{acme-directory-url}}" --target iis --host {{hostname}} --validationmode http-01 --webroot "C:\temp" --store certificatestore --installation iis

Tip

In some cases, you may want to use --siteid {{iis-site-id}} instead of --host {{hostname}}. The –webroot destination may be set to any directory on the server.

Note

If you want to include additional hostnames (SANs) in the SSL certificate you are trying to get issued, then add --host {{hostname}} per SAN in the SSL certificate.

If you want to specify in the IIS where to place the certificate once it is issued, then you can specify it in this format: --certificatestore My\Trusted by replacing this part --store certificatestore in the simple-acme command above.

This is the output of an example run:

Example run of a simple-acme command¶

C:\Program Files\simple-acme.v2.1.23.1315.x64.pluggable> .\wacs --baseuri https://trustview-instance-url/acme/?token=e03f0dba-b6f7-46cc-8508-69526903d3d1 --target iis --host demo.adtest.local --validationmode http-01 --webroot "C:\temp" --store certificatestore --installation iis

A simple Windows ACMEv2 client (WACS)
Software version 2.1.23.1315 (release, pluggable, standalone, 64-bit)
Connecting to https://trustview-instance-url/acme/?token=e03f0dba-b6f7-46cc-8508-69526903d3d1...
Connection OK!
Scheduled task looks healthy
Please report issues at https://github.com/simple-acme/simple-acme
Running in mode: Unattended
Source generated using plugin IIS: demo.adtest.local

Cached order has status pending, discarding
[demo.adtest.local] Authorizing...
[demo.adtest.local] Authorizing using http-01 validation (SelfHosting)

... Continued after the Automation agent has been activated inside TrustView ...

[demo.adtest.local] Authorization result: valid
Downloading certificate [IIS] (any site), demo.adtest.local
Store with CertificateStore...
Installing certificate in the certificate store
Adding certificate [IIS] (any site), demo.adtest.local @ 20XX/X/XX 9:53:01 to store WebHosting
Installing with IIS...
Adding new https binding *:443:demo.adtest.local
Committing 1 https binding changes to IIS while updating site 2
Scheduled task looks healthy
Adding renewal for [IIS] (any site), demo.adtest.local
Next renewal due at 20XX/X/XX 9:53:22
Certificate [IIS] (any site), demo.adtest.local created
C:\Program Files\simple-acme.v2.1.23.1315.x64.pluggable>

Step 2b

Initial run of simple-acme with wildcard certificate

Execute simple-acme for the first time using a wildcard certificate. You must replace {{acme-directory-url}} to match your configuration. You can find the {{acme-directory-url}} here; it can also be found inside TrustView under the Automation menu section.

simple-acme command to run if you are using a wildcard certificate¶

.\wacs.exe --baseuri "{{acme-directory-url}}" --source manual --host *.domain.com --validationmode dns-01 --validation script --dnscreatescript C:\temp\dnsvalidationscript.ps1 --store certificatestore --certificatestore My --nocache --accepttos --emailaddress {{email}} --installation iis --installationsiteid {{IIS siteid}}

For reference regarding targeting specific or all bindings for IIS sites, you can find more information here: simple-acme IIS reference.

Step 3

Activate the agent in TrustView

Follow the steps described here to activate the Automation agent. Once that is done, the automation cycle will run and automatically renew the certificate when nearing expiry.

If the command has timed out (and you did not activate it inside TrustView in time), from whatever terminal it has been run from e.g. PowerShell or Bash, it may need to be executed again.

Step 4

Configure simple-acme to run periodically

simple-acme automatically creates a scheduled task that periodically runs simple-acme and renews certificates, so there is no manual configuration required.

simple-acme defaults to starting renewal 55 days before expiry, but that can be adjusted in the settings.json file.

Look for this section in the file and adjust as needed:

"ScheduledTask": {
  "RenewalDays": 55,
  "RenewalDaysRange": 0,
  "RenewalMinimumValidDays": null,
  "RandomDelay": "04:00:00",
  "StartBoundary": "09:00:00",
  "ExecutionTimeLimit": "02:00:00"
},

You can also adjust the scheduled task for the simple-acme client on the Windows server.

7. Use simple-acme to automatically issue and renew a certificate on Apache Tomcat

Note

The minimum required version of simple-acme is v2.1.19.1142.

First, make sure to update the following line in the settings.json file:

"RetryCount": 150

Step 1

Initial run of simple-acme

You will need a .pfx file for this to work, so use --store pfxfile to save the certificate as a PFX file. --pfxpassword {{password}} will define the password for the certificate so it does not change. --pfxfilename {{CertName}} will define the name and make sure the PFX certificate will have the same name after renewal and --pfxfilepath {{Cert-Path}} to define where it should save the PFX file, as shown in the PowerShell command below.

Use the PowerShell command, with the following parameters:

.\wacs.exe --baseuri {{acme-directory-url}} --validationmode http-01 --webroot "C:\temp" --source manual --host {{Hostname}} --store pfxfiles --pfxpassword {{Password}} --pfxfilespath {{Cert-Path}} --pfxfilename {{certname}}

Note

Remember to change {{acme-directory-url}}, {{Hostname}} , {{Cert-path}}, {{Password}} and {{certname}}.

Step 2

Configure Apache Tomcat to use new SSL certificate

On the Embedded version of TrustView, the trustview.groovy file and the SSL certificate can both be found here:

Location of the config file and the SSL certificate¶

 C:\Program Files\TrustView-Embedded\Conf

The following is an example of the Connector element to look for in that file:

<Connector
port="443"
maxhttpheadersize="8192"
maxThreads="150"
minsparethreads="25"
maxsparethreads="75"
enablelookups="false"
disableuploadtimeout="true"
acceptcount="100"
scheme="https"
secure="true"
sslProtocol="TLS"
clientAuth="true"
SSLEnabled="true"
keystoreFile="conf/trustview_ssl.p12"
keystorePass="Test1234"
keystoreType="PKCS12"
/>

Important

Always make sure you have a backup of the trustview.groovy file before modifying it.

Now update the following attributes of the Connector element to match the path, filename and password defined in simple-acme, then restart the Embedded TrustView service for the change to take effect:

keystoreFile

keystorePass

Important

If you are still using the Standalone version of TrustView, there is no trustview.groovy file - locate the Tomcat installation directory instead, typically:

Directory path of the Tomcat installation (Standalone version)¶

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView

The SSL certificate is specified there in the Tomcat Apache server.xml configuration file, Tomcat-install-dir\conf\server.xml, using the same Connector element attributes shown above. Update it the same way, then restart the Apache Tomcat service instead.

Tip

If you are unable to locate the Apache Tomcat directory, contact our Support for assistance.

Step 3

Run a script to restart Apache Tomcat service

Follow the steps described here to run a script after a renewal of a certificate and run the following script:

Batch script:

net stop "myservice"

net start "myservice"

PowerShell script:

Restart-Service -displayname "Service name"

Tip

In this case, the service name would most likely be TrustView, but check the properties of the Windows service, if in doubt.

Important

If you are using the Embedded version of TrustView, the service name will be different - it is whatever name was given when the service was installed (see the Embedded installation steps in Maintenance), so check the properties of the Windows service to confirm it, rather than assuming TrustView.

9. Use simple-acme to automatically issue and renew certificates for Azure Key Vault

Step 1

Install and configure simple-acme

Note

This plugin requires you to use the pluggable release of the main executable, which you can find here.

Start by downloading simple-acme and unpack it in a directory on the Windows server that you want to automate certificate renewal on. To use Azure with simple-acme we need to download and install a plugin. This plugin is offered as a separate download, and it has to be moved to the simple-acme directory and unpacked.

simple-acme store keyvault plugin

simple-acme releases

Note

After unpacking, you may have to unblock all new .dll files before .NET will trust them. You can do that from the Windows File Explorer by going into Properties of the files and then checking the Unblock box in the General tab.

Step 2

Azure configuration

Azure Key Vault is a cloud service that provides a secure store for keys, secrets, and certificates.

How to create Azure key vault:

Follow this guide: Azure key vault guide

An App registration establishes a trust relationship between your app (simple-acme) and Microsoft Azure.

How to create app registration:

Follow this guide: Azure app guide

When both have been created, you have to give the App registration access to your key vault.

Note

Give full permission in Key Permissions, Secret Permissions and Certificate Permissions.

How to assign an access policy to an Azure key vault:

Access policy guide

Step 3 [Optional]

Set up DNS integration

To get Let’s Encrypt certificates issued, they need to be validated with a DNS challenge, which happens through the DNS integration. See DNS integration for details.

Step 4

Use simple-acme with Azure Key Vault

When running simple-acme it will need the following to authenticate with Azure:

Directory/Tenant ID
Application client ID
Application client secret

The Directory/Tenant ID can be found under Azure Active Directory:

The Application client ID can be found under your App registration:

The Application client secret can also be found under your App registration:

Note

You have to create a client secret first, and the value will only be shown once, so remember to save it.

Execute simple-acme for the first time.

Note

You must replace {{acme-directory-url}}, {{Key-vault-name}}, {{Name-of-cert-in-azure}}, {{Hostname}}, {{Directory/tenant id}}, {{Application client id}} and {{Application client secret}} to match your configuration.

./wacs.exe --baseuri "{{acme-directory-url}}" --Store keyvault --source manual --vaultname "{{Key-vault-name}}" --Certificatename “{{Name-of-cert-in-azure}}” --Host “{{Hostname}}” --azureenvironment azurecloud --azuretenantid “{{Directory/tenant id}}” --azureclientid “{{Application client id}}” --azuresecret “{{Application client secret}}”

Important

The --Certificatename parameter must be a name without spaces or extensions such as .dk and .com etc. An example for a valid name would be certificateName or exampleCom.

Step 5

Activate the agent in TrustView

Follow the steps described here to activate the Automation agent.

Now the activated certificate should be in the Azure Key Vault under Certificates.

This is the output of an example run:

C:\Program Files\Acme> ./wacs.exe --baseuri https://trustview-instance-url/acme/?token=6b8e06fa-0ea0-4a78-a1d2-c4e0a38a09d8 --store keyvault --vaultname AcmeTest --certificatename test1  --host azuretest4.dk --azureenvironment azurecloud --azuretenantid a6fb3859-****-****-****-**** --azureclientid de12ab67-****-****-****-**** --azuresecret Y43g************ --source manual

A simple Windows ACMEv2 client (WACS)
Software version 2.1.20.1185 (release, pluggable, standalone, 64-bit)
Connecting to https://tv-staging.trustskills.com:11443/acme/?token=6b8e06fa-0ea0-4a78-a1d2-c4e0a38a09d8...
Scheduled task looks healthy
Please report issues at https://github.com/simple-acme/simple-acme
Running in mode: Unattended
Source generated using plugin Manual: azuretest4.dk

[azuretest4.dk] Authorizing...
[azuretest4.dk] Authorizing using http-01 validation (SelfHosting)
[azuretest4.dk] Authorization result: valid
Downloading certificate [Manual] azuretest4.dk
Store with KeyVault...
Installing with None...
Scheduled task looks healthy
Adding renewal for [Manual] azuretest4.dk
Next renewal scheduled at 20XX/XX/XX 10.13.11
Certificate [Manual] azuretest4.dk created

12. Automation of certificate renewal on Palo Alto firewall using Certbot

Step 1

Setup and installation

Requirements:

Linux-based container or virtual machine with reachability to the Palo Alto firewall management interface
Certbot
OpenSSL
pan-python

Follow the steps on the Linux-based container or VM.

Run the installation commands:

sudo apt-get install python3-pip certbot openssl
sudo pip install pan-python

Generate an API key, if you do not already have one available:

panxapi.py -h PAN_MGMT_IP_OR_FQDN -l USERNAME:'PASSWORD' -k

Note

The example is shown with DigiCert certificates, but can be used with Certum, GeoTrust and Let’s Encrypt certificates or certificates from the ADCS module. Just select the type you want to use under the relevant automation agent - Certificate issuer dropdown menu. With DigiCert, GeoTrust and Certum certificates, we need to enable automation on our side; in that case, contact our Support to let us know.

Let’s Encrypt certificates require a DNS integration to be set up in TrustView
ADCS certificates require the installation of the ADCS module and a specific CRL flag to be set on the CA
Certum, GeoTrust and DigiCert require prevalidation for the OV and EV certificates and to have automation enabled in our backend

If you want to use ADCS certificates, this CRL flag must be set on the CA:

certutil -setreg ca\CRLFlags +CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT

This is an example of the output:

C:\Windows\system32> certutil -setreg ca\CRLFlags +CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\CertSvc\Configuration\Adtest Root CA\CRLFlags:

Old Value:
  CRLFlags REG_DWORD = 2
    CRLF_DELETE_EXPIRED_CRLS -- 2

New Value:
  CRLFlags REG_DWORD = 10002 (65538)
    CRLF_DELETE_EXPIRED_CRLS -- 2
    CRLF_ALLOW_REQUEST_ATTRIBUTE_SUBJECT -- 10000 (65536)
CertUtil: -setreg command completed successfully.
The CertSvc service may need to be restarted for changes to take effect.
C:\Windows\system32>

This will allow the subject field to be filled out on ADCS certificates, when retrieving the certificate through the automation agent. If this step is skipped, an error will occur during the deployment step.

Step 2

Set up deploy script

Write your own deploy script or use this pre-made script paloalto.bash.

The script handles a single certificate and SSL/TLS service profile. To accommodate more certificates and SSL/TLS service profiles, you either need to use separate scripts or configure the pre-made script to handle additional ones.

Important

There must be no spaces in the name of the SSL/TLS service profiles. Replace them with underscores, dashes or other characters.

Step 3

Set up crontab

To set up the automation for certificate retrieval and deploy script, you can use a crontab to schedule when to run the renewal and deployment process.

sudo crontab -e

Inside the crontab, the setup could be like this:

0 0,12 * * * /usr/bin/certbot certonly -q --apache -m {{email}} --agree-tos --server {{acme-directory-url}} -d example.cryptomathic.com --deploy-hook /pathto/deployscript

If you have a single deploy script for a single certificate and SSL/TLS service profile, then you should use the example above and add additional lines if you have more than one single certificate and SSL/TLS service profile.

The crontab above is set to run twice a day (every 12 hours). So every day it checks if a certificate needs to be renewed and 30 days before expiry, the renewal process will begin automatically.

Important

It is recommended to run each line in the crontab outside the crontab in the terminal once, both to test the renewal process for errors and to issue the first certificate and to be able to activate the automation agent. Use the --dry-run parameter to test if the command would be successful without actually renewing the certificate. Also change the -q parameter to -n when running the command outside the crontab. -n non-interactive will show logging in the terminal and -q quiet will show nothing, which is recommended when run inside a crontab.

15. Run a script after issuing or renewing certificate with simple-acme

Add the following parameters at the end of the simple-acme command, and remember to change {{Script-path}} to match your configuration.

--installation script --script {{script-path}}

Script Parameters

The following variables can be specified at the end of the simple-acme command as command-line arguments, which the script can use after retrieving the certificate.

Remember to change {{Script-path}} and {{parameters x}} to match your configuration.

--installation script --script {{script-path}} --scriptparameters {{parameterX}}

Value	Replaced with
{0} or {CertCommonName}	Common name (primary domain name) of the newly issued certificate
{1} or {CachePassword}	The `.pfx` password (generated randomly for each renewal)
{2} or {CacheFile}	Full path of the cached `.pfx` file
{4} or {CertFriendlyName}	Friendly name of the newly issued certificate
{5} or {CertThumbprint}	Thumbprint of the newly issued certificate
{7} or {RenewalId}	Id of the renewal
{3} or {6} or {StorePath}	Path or store name used by the (first) store plugin
{StoreType}	Name of the plugin (CentralSsl, CertificateStore or PemFiles)
{OldCertCommonName}	Common name (primary domain name) of the previously issued certificate
{OldCertFriendlyName}	Friendly name of the previously issued certificate
{OldCertThumbprint}	Thumbprint of the previously issued certificate

If you need your script parameters to look something like this:

--scriptparameters action=import file=C:\mydomain.pfx password=*****

Then your argument string should look like this:

--scriptparameters action=import file={CacheFile} password={CachePassword}

16. Use simple-acme to automatically issue and renew the certificate on an on-premises Exchange Server

This applies to on-premises Exchange Server 2016, 2019 and Subscription Edition (SE). It does not apply to Exchange Online, and the script below does not support Exchange 2010 or earlier, which load the Exchange Management Shell differently.

Important

simple-acme (and the script below) must run directly on the Exchange server itself - importing a certificate and enabling it for Exchange services both require the Exchange Management Shell cmdlets and the server’s local certificate store.

Note

The Scripts folder bundled with simple-acme also contains older ImportExchange.ps1 scripts, left over from before TrustView switched its recommended ACME client from win-acme to simple-acme. Those scripts predate Exchange 2013 and are not maintained - use the script below instead.

Step 1

Initial run of simple-acme

.\wacs.exe --baseuri "{{acme-directory-url}}" --validationmode http-01 --webroot "C:\temp" --source manual --host {{Hostname}} --store pfxfile --pfxfilepath {{Cert-Path}} --installation script --script "C:\scripts\ImportToExchange.ps1" --scriptparameters "-CertThumbprint '{CertThumbprint}' -CacheFile '{CacheFile}' -CachePassword '{CachePassword}' -CertFriendlyName '{CertFriendlyName}' -ExchangeServices 'IIS,SMTP,IMAP,POP' -OldCertThumbprint '{OldCertThumbprint}'"

Tip

Remember to change {{acme-directory-url}}, {{Hostname}} and {{Cert-path}} to match your configuration, and adjust the -ExchangeServices list to the services you want the certificate bound to - see Step 3 below.

Important

Keep the quoting exactly as shown: double quotes around the whole --scriptparameters value, and single quotes around each value inside it. simple-acme hands this string to PowerShell to parse, so the quotes make sure that:

'IIS,SMTP,IMAP,POP' reaches the script as the intended list of services.
'{OldCertThumbprint}' is still a valid (empty) argument on the first issuance, when there is no previous certificate. Unquoted, the command line would end in -OldCertThumbprint with no value, and PowerShell would fail before the script starts.
Paths and passwords containing spaces or special characters reach the script intact.

Note

--store pfxfile --pfxfilepath {{Cert-Path}} tells simple-acme to just cache the issued certificate as a .pfx file at that path, rather than installing it into the Windows certificate store itself. The script does the actual import, via Exchange’s own Import-ExchangeCertificate cmdlet, using the cached file and password simple-acme passes it as {CacheFile}/{CachePassword}.

If the certificate ends up in the server’s Personal (My) certificate store some other way - for example by switching to --store certificatestore --certificatestore My instead - the script detects that automatically and skips the import step, going straight to Enable-ExchangeCertificate. Either option works with this script.

Follow the steps described here to activate the Automation agent in TrustView after running simple-acme the first time.

Step 2

Download the script

ImportToExchange.ps1

Copy it to C:\scripts on the Exchange server, or adjust the --script path in Step 1 to wherever you place it.

Step 3

Choosing Exchange services

-ExchangeServices takes a comma-separated list in single quotes, for example -ExchangeServices 'IIS,SMTP,IMAP,POP'. Valid values, per Microsoft’s current Enable-ExchangeCertificate documentation, are:

Federation
IIS
IMAP
POP
SMTP
UM (Unified Messaging)
UMCallRouter

Note

Services are additive on a given certificate - once a service is enabled on a certificate it cannot be removed from it again; enable a different certificate for that service instead.

Important

List every service the previous certificate was enabled for. The script removes the previous certificate (-OldCertThumbprint) after enabling the new one, so a service missing from the list - for example IMAP or POP - is left pointing at a certificate that is being removed, or the removal fails and the old certificate stays behind.

Check the result

After the first issuance and after each renewal, check which services the new certificate is enabled for:

Get-ExchangeCertificate | Format-List Thumbprint, Subject, NotAfter, Services

If a service is missing, enable it by hand with the new thumbprint, then correct the -ExchangeServices list in the renewal so the next renewal gets it right:

Enable-ExchangeCertificate -Thumbprint <thumbprint> -Services IIS,SMTP,IMAP,POP -Force

-Force stops Exchange from prompting before it replaces the default SMTP certificate, which would otherwise stall an unattended run. The script always passes it.

Note

Every renewal produces a certificate with a new thumbprint - the thumbprint is a hash of the whole certificate, including its serial number and validity dates, so it cannot be kept the same. The script enables the new thumbprint for you on each renewal. Anything else that references the certificate by thumbprint has to be updated as well; send and receive connectors that use TlsCertificateName match on issuer and subject instead, so they keep working as long as those don’t change.

18. Use an external ACME client (Certbot) to issue a certificate and push it to a FortiGate

Where FortiGate’s native ACME client (see the previous example) doesn’t fit - a wildcard or multi-SAN/multi-domain certificate is needed, DNS-01 validation is preferred so the FortiGate itself never has to expose port 80, or the same certificate needs to be pushed to several FortiGates from a single renewal - request the certificate with an external ACME client instead and push it into the FortiGate’s certificate store over SSH.

Note

This uses FortiGate’s plain certificate import mechanism, not its ACME client - the two are independent and this example doesn’t touch config system acme at all. See the previous example instead if the simpler, single-domain, HTTP-01-only native client already covers your case.

Step 1

Install Certbot and request the certificate

Install Certbot on a host that can reach TrustView’s ACME server - this doesn’t need to be the FortiGate itself, and that host doesn’t need to be reachable from any of the FortiGate’s own interfaces. Request the certificate using whichever validation method TrustView’s integration supports for your domain - see DNS Integration for DNS-01, or the Apache/Certbot example above for HTTP-01 against TrustView’s own challenge verification.

Tip

A wildcard or multi-SAN certificate requires DNS-01 validation; HTTP-01 only covers a single hostname per certificate, the same restriction the native client has.

Step 2

Download the deployment script

fortigate_deploy.py

Requires Python 3 and the OpenSSH client (ssh) on the Certbot host - no extra Python packages need to be installed.

Important

This script has been code-reviewed and logic-tested, including a mocked SSH session covering both the success and failure paths, but it has not been run against a live FortiGate. Test it in a non-production environment before relying on it for certificate renewals.

Step 3

Set up SSH access on the FortiGate

Create a dedicated FortiGate administrator account for this purpose, and give it an SSH public key for key-based login (config system admin / set ssh-public-key1) - this keeps a password out of a scheduled job’s environment entirely. Password authentication is also supported via --ssh-password, but it requires sshpass to be installed on the Certbot host and is not recommended.

Tip

Give the account an access profile with System Configuration and VPN set to Read-Write (sysgrp/vpngrp in config system accprofile) - that’s enough to run config vpn certificate local and bind the certificate; super_admin is not required.

Important

The deployment script accepts the FortiGate’s SSH host key on first connection (StrictHostKeyChecking=accept-new) rather than verifying it. Before running it for the first time, connect to the FortiGate over a trusted path (console or the admin GUI) and run get system info admin ssh to record its host key fingerprint, then confirm it matches the key presented on that first SSH connection - check the entry the script adds to the Certbot host’s ~/.ssh/known_hosts file.

Step 4

Run it as a Certbot deploy hook

certbot renew --deploy-hook "python3 /path/to/fortigate_deploy.py --host {{FortiGate-IP}} --user trustview-svc --ssh-key /home/user/.ssh/id_ed25519 --cert-name trustview-cert --bind-admin-gui"

Certbot runs the deploy hook after every successful issuance and renewal, setting $RENEWED_LINEAGE so the script picks up the new certificate and key automatically - --cert-file/--key-file are only needed when running the script by hand, outside a deploy hook. Add --bind-ssl-vpn as well (or instead of --bind-admin-gui) to also bind the certificate to the SSL-VPN portal.

Tip

Run the same certbot renew command once by hand first, to confirm both the certificate request and the deploy hook succeed, before leaving it to the scheduler.

1.9. Change the renewal interval for simple-acme¶

Go to the settings.json file and look for the following settings:

RenewalDays [Default: 55] - The number of days after which a certificate is renewed.
StartBoundary [Default: “09:00:00”] - Configures the start time for the scheduled task.
RandomDelay [Default: “04:00:00”] - Configures a random delay before starting the scheduled task. This spreads the load on the servers and thus prevents users from getting TooManyRequests errors.

1.10. Automate activation of agent connections (Activation templates)¶

Instead of manually activating agent connections from ACME clients, it is possible to automate the activation process using activation templates.

If a new ACME client matches an active activation template, the ACME client will automatically be activated using the information defined for the activation template.

The list of activation templates created is available on the Activation templates page.

1.11. Custom fields on activation templates¶

Activation templates support the same 10 custom fields available on other monitored objects, and they can be filled in on the template’s create/edit form.

When an ACME client auto-activates against a matching template, the template’s custom field values are copied onto the resulting automation agent connection.

Important

These custom field values currently do not carry any further than the automation agent connection - the certificate that agent connection later issues is left with its custom fields unset, regardless of what was set on the template or the agent connection. Keep this in mind if you’re relying on custom fields for reporting or automation further down the certificate lifecycle.

1.12. Troubleshooting¶

1.14. Deleting certificates in Certbot¶

There are two methods for deleting certificates issued with Certbot. These examples are for a Linux-based environment.

Automatic method
Use this command to list all Certbot certificates:
sudo certbot certificates
Then use this command to specify which certificate to delete:
sudo certbot delete --cert-name example.cryptomathic.com
Manual method
To delete them manually, go into each of the following folders:
1/etc/letsencrypt/archive
2/etc/letsencrypt/live
3/etc/letsencrypt/renewal
Once inside each folder, delete all the certificates that need to be deleted.
sudo rm cert.pem
The manual method will give more control over which file to delete, but may be more tedious than the automatic method.

1.15. Automating with SCEP¶

To automate with SCEP, a client that supports the SCEP protocol is required. This means that simple-acme and Certbot cannot be used, since they are clients used with the ACME protocol.

Step 1
Before SCEP automation agents can be used, you need to add the following 4 lines (or configure them, if they already exist) to your TrustView.groovy configuration file:
1scepserver.enabled=true
2scepserver.keystore="insert certificate"
3scepserver.keystore_password="insert keystore password"
4scepserver.keystore_type="PKCS12"
After the lines have been added and configured, save the configuration file and restart the TrustView Tomcat service for the changes to take effect.

Important

Since the client is expected to perform signature verification and optionally encryption using the CA certificate, the keyUsage extension in the CA certificate MUST indicate that it is valid for digitalSignature and keyEncipherment.
Step 2

In TrustView, go to Agents in the left menu and click Add SCEP in the toolbar, to create a SCEP automation agent.

Once the agent has been created, a Shared secret will automatically be generated and be available for you to use in a command for your SCEP client of your choice.

Step 3

Enter a name for the SCEP agent and fill out the IP subnets and Hostname matcher. Lastly select a Certificate issuer and click Update to activate the agent.

Important

Save the Shared secret, as it is required for connecting to the SCEP server, which in this instance is TrustView.

Step 4
Now that the SCEP agent is configured in TrustView, a command can be run to execute a certificate issuance. The structure and parameters of the command depend completely on the SCEP client used. On a Windows server, the command can be run from PowerShell or from a CLI on a Linux server.

Here is an example of what it could look like for a SCEP client used on Windows, using this SCEP client:
 1PS C:\temp\scepclient-windows-amd64-v2.2.0> .\scepclient-windows-amd64.exe -debug -server-url https://trustview-instance-url/scep -cn "domain.example.com" -challenge "=i8Fy_!MfdgSEs1F" -private-key "C:\temp\privatekey.key"
 2level=info ts=20XX-XX-31T13:27:00.0206502Z op=GetCACert error=null took=179.674ms
 3level=debug ts=20XX-XX-31T13:27:00.0248159Z msg=cacertlist count=3
 4level=debug ts=20XX-XX-31T13:27:00.026347Z msg=cacertlist number=0 rdn="CN=EndEntity,O=Organization,L=City,ST=State,C=US" hash_type=SHA-256 hash=e4505b4c6bc3070fd8a12d60e7b3ae250021d0632a551b8bb57c0a37a2d30bab
 5level=debug ts=20XX-XX-31T13:27:00.0264065Z msg=cacertlist number=1 rdn="CN=IntermediateCA,O=Organization,L=City,ST=State,C=US" hash_type=SHA-256 hash=4fce3213e58c9c4b0c4f733358f16e5211e2ee2efa1ec9104ab324f7943d05a0
 6level=debug ts=20XX-XX-31T13:27:00.0264065Z msg=cacertlist number=2 rdn="CN=RootCA,O=Organization,L=City,ST=State,C=US" hash_type=SHA-256 hash=a04ab5ffd3f0ff4efed89380f7a47fc6b2a960ea374569fec36e0a9739af74b4
 7level=debug ts=20XX-XX-31T13:27:00.0275331Z msg="creating SCEP CSR request" transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM=" signer_cn="SCEP SIGNER"
 8level=info ts=20XX-XX-31T13:27:00.0618626Z op=GetCACaps error=null took=32.6128ms
 9level=info ts=20XX-XX-31T13:27:00.3175644Z op=PKIOperation error=null took=255.3966ms
10level=debug ts=20XX-XX-31T13:27:00.3180724Z msg="parsed scep pkiMessage" scep_message_type="CertRep (3)" transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM="
11level=info ts=20XX-XX-31T13:27:00.3191155Z pkiStatus=PENDING msg="sleeping for 30 seconds, then trying again."
12level=info ts=20XX-XX-31T13:27:30.6087161Z op=PKIOperation error=null took=289.2402ms
13level=debug ts=20XX-XX-31T13:27:30.6098253Z msg="parsed scep pkiMessage" scep_message_type="CertRep (3)" transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM="
14level=info ts=20XX-XX-31T13:27:30.6098253Z pkiStatus=SUCCESS msg="server returned a certificate."
15level=debug ts=20XX-XX-31T13:27:30.6123552Z msg="decrypt pkiEnvelope" ca_certs=3
16PS C:\temp\scepclient-windows-amd64-v2.2.0>
Note

In the example above, the -challenge refers to the value of Shared secret from the detail page, for the SCEP automation agent in TrustView.

1.16. ACME External Account Binding (EAB)¶

It is possible to use EAB with TrustView ACME endpoints, when using automation.

Note

EAB will only work for ACME clients that support it. See the ACME standard for more information. It will work with the ACME clients simple-acme and Certbot.

Go to Agents Agent client info. Then click on the ACME Directory Resource URI link (there may be multiple) that you wish to set up EAB for. If there are none, simply click Add to create one.

Important

EAB will only work for new accounts and will not work for existing ACME accounts.

On the detail page for the ACME Directory Resource URI, check Use ACME external account binding (EAB) to enable it. Before running an ACME client command, take note of the following:

ACME EAB key ID
ACME EAB key

Next, you need to run the command to register a new account. Here is an example for simple-acme:

Example of a PowerShell command to register a new account in simple-acme¶

 .\wacs.exe --register --baseuri "{{acme-directory-url}}" --eab-key-identifier "{{acme-eab-key-id}}" --eab-key "{{acme-eab-key}}" --eab-algorithm HS256 --emailaddress example@domain.com --accepttos

Then you need to run the actual certificate issuance command separately from the account registration command:

Example of a PowerShell command to issue an SSL certificate with simple-acme¶

 .\wacs.exe --baseuri "{{acme-directory-url}}" --source manual --host "{{hostname}}" --validationmode dns-01 --validation script --dnscreatescript "C:\temp\dnsvalidationscript.ps1" --store certificatestore --certificatestore My --installation iis --installationsiteid {{siteid}} --nocache --accepttos

Here is a list of relevant simple-acme commands:

–register (Register an account)
–eab-key-identifier (Find the EAB key ID inside TrustView)
–eab-key (Find the key inside TrustView)
–eab-algorithm (The HMAC algorithm, such as HS256 (default), HS384, and HS512)

You can see the details for all the simple-acme commands here.

1. Automation¶

1.1. Automation tasks¶

1.2. Automation using ACME clients¶

1.3. Hostnames and IPs used during automation¶

1.4. ACME challenge checking¶

1.5. simple-acme and Certbot logs¶

1.6. Customize the ACME URL directory path¶

1.7. Tune the ACME server’s own behavior¶

1.8. Automation examples¶

1.9. Change the renewal interval for simple-acme¶

1.10. Automate activation of agent connections (Activation templates)¶

1.11. Custom fields on activation templates¶

1.12. Troubleshooting¶

1.13. Automation agent related tasks in TrustView¶

1.14. Deleting certificates in Certbot¶

1.15. Automating with SCEP¶

1.16. ACME External Account Binding (EAB)¶