Using TrustView for automation requires a license to 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:
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.
To get an overview over 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 a ACME client on a server (e.g. win-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 Entrust, DigiCert or GeoTrust certificates (external certificates) the domain(s) must be prevalidated for the OV and EV type.
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:
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.
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 and outbound HTTPS connection - port443
Connect outbound to view.trustskills.com - port443
This will only work from v5.26.163 of TrustView and onwards.
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 file.
acmeContextPrefix="https://acme.example.org"
Or
acmeContextPrefix="http://acme.example.org"
After the line has been added or adjusted as needed, save the file and restart the TrustView service, for it to take effect.
Start by downloading win-acme and unpack it in a directory, on the Windows server you
want to automate certificate renewal on. As long as the win-acme folder is not zipped or archived, the location is not important.
Tip
Even though win-acme can be run from anywhere on the server, it is still recommended to place the win-acme directory in a location that does not get deleted or removed.
e.g."C:\Program Files\win-acme"
Next, 1 additional step is required to allow win-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 win-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 win-acme, because
external CA’s such as Entrust and DigiCert will no longer allow wildcard SSL certificates to be validated through a HTTP-01challenge.
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 win-acme command.
Start by creating a PowerShell script containing the following:
exit0
Name it dummy.ps1 (or other relevant name) and place it in a temp folder on the C: drive of the server, where win-acme is placed,
or in any other directory, as long as you remember to adjust the command.
Initial run of win-acme without wildcard certificate
Execute win-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,
but it can be found inside TrustView under the Automation menu section.
win-acme command to run if you are not using a wildcard certificate#
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:
--certificatestoreMy\Trusted by replacing this part --storecertificatestore in the win-acme command above.
Execute win-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,
but it can be found inside TrustView under the Automation menu section.
win-acme command to run if you are using a wildcard certificate#
For reference regarding targeting specific or all bindings for IIS sites, you can find more information here: win-acme IIS reference.
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, from whatever terminal it has been run from e.g. PowerShell or Bash, it may need to be executed again.
Configure win-acme to run periodically
win-acme automatically creates a scheduled task that periodically runs win-acme and
renews certificates, so there is no manual configuration required.
Win-acme defaults to start 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:
You can also adjust the scheduled task for the win-acme client on the Windows server.
2. Specify certificate name manually on the IIS
In some cases, you may want to specify the certificate name manually and bind it to the hostname, instead of
automatically using the hostname of the IIS as the certificate name.
This can currently only be done by running the win-acme wacs.exe and not by using PowerShell and parameters.
Follow the instructions on screen:
Type MCreatecertificate(fulloptions)
Type MManualinput
Type the desired hostname (the name of the certificate)
Press Enter to accept the hostname as the friendly name (unless you wish to change it)
Type 1[http-01]Saveverificationfileson(network)path
Type the network path, e.g. C:\temp
Type n as it’s not necessary to Copydefaultweb.configbeforevalidation
Type 2RSAkey
Type 5WindowsCertificateStore
Type 1 or 3 for WebHosting
Type 6No(additional)storesteps
Type 1CreateorupdatebindingsinIIS
Type 1default
Type 3No(additional)installationsteps
The win-acme should now run, issue the certificate and update the IIS binding
3. Issue wildcard certificate and update bindings in IIS using win-acme without the IIS plugin
When using win-acme and the integrated IIS-plugin, win-acme insists on creating bindings in IIS.
In some cases this is not desirable. In this example we utilize win-acme with a custom script instead of the IIS-plugin for updating certificates in IIS.
Remember to adjust the {{acme-url}}, {{hostnames}} and {{email}} to fit your needs.
Activate the agent connection in TrustView (if necessary).
Update all relevant bindings in IIS to use the new certificate.
Now, during certificate renewal, win-acme will automatically detect all bindings in IIS that uses
the old certificate and replace the certificate with the renewed certificate.
4. Use win-acme to automatically renew certificates on multiple bindings and sites of an IIS
If you want to automate the deployment of certificates on an IIS and have multiple sites
and/or bindings, you need to utilize this command parameter:
--installationsiteid{{id}}
As stated here the command will
use the name of all the bindings (if more than one) from the chosen siteid, so you have to make preparations for that before running
the automation command with win-acme, by making sure all the bindings you wish to hit, has the exact same name.
Example:
An IIS setup has 3 sites (id 10, 11 and 12), and each site have 3 bindings. These bindings have a wildcard certificate (*.) attached that contain the exact same name.
Binding 10 in this example has been chosen, but because the remaining 2 sites have bindings that contain a wildcard certificate with the same name,
they will also automatically be renewed in the process, and therefore they do not need to be specified with the --installationsiteid command.
If you wish, bindings can be excluded with this command parameter:
5. Deploy certificate from the Certificate Store to the IIS
If you wish to deploy one or more certificates from your Microsoft Certificate Store
to your IIS, you can do so by running a script at the end of the win-acme renewal process.
Below is a script you can use and configure for your needs, as a starting point:
The following files will be created when --storepemfiles is used:
{CommonName}-crt.pem (certificate)
{CommonName}-key.pem (private key)
{CommonName}-chain.pem (certificate plus chain)
{CommonName}-chain-only.pem (chain without certificate)
Optionally {CommonName}-key.pem can be password protected by adding --pempassword{{password}} at the end.
If you need a .pfx file, use --storepfxfile and --pfxfilepath{{Cert-Path}} instead.
Tip
Remember to change {{acme-directory-url}}, {{Hostname}} and {{Cert-path}} to where you want your certificates to be stored, to match your configuration.
7. Use win-acme to automatically issue and renew a certificate on Apache Tomcat
Note
Minimum version required of win-acme is v2.1.19.1142.
First, make sure to update the following line in the settings.json file:
"RetryCount":150
Initial run of Win-acme
You will need a .pfx file for this to work, so use --storepfxfile 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:
If you are unable to locate the Apache Tomcat directory, contact our Support for assistance.
The SSL certificate is specified in the Tomcat Apache server.xml configuration file
Tomcat-install-dir\conf\server.xml. The following is an example of such Connector element:
You can also follow the installation instructions provided by the Certbot website.
Initial run of Certbot
Execute Certbot for the first time. How you find your {{acme-directory-url}} is described here, but it can be found inside TrustView under the Automation menu section.
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.
Configure Certbot to run periodically
You can set up a cron job or scheduled task to make Certbot run periodically. When using the renew command inside a cron job, it defaults to attempt renewal of certificate 30 days before expiry.
Cron job example:
00***certbotrenew--quiet
This will make the cron job run every day at midnight.
Important
Note that some OS distributions come with preconfigured scheduled renewal
of certificates configured with Certbot using e.g. systemd or cron (depending
on the method you used for installing Certbot).
9. Use win-acme to automatically issue and renew certificates for Azure Key Vault
Install and configure win-acme
Note
This plugin requires you to use the pluggable release of the main executable,
which you can find here.
Start by downloading win-acme and unpack it in a directory on the Windows server, that you want to automate certificate renewal on.
To use Azure with win-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 Win-acme directory and unpacked.
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.
Azure configuration
Azure Key Vault is a cloud service that provides a secure store for keys, secrets, and certificates.
To get Lets Encrypt certificates issued, they need to be validated with a DNS challenge, which happens through the DNS integration.
See DNS integration for details.
Use win-acme with Azure Key Vault
When running win-acme it will need the following to authenticate with Azure:
Directory/TenantID
ApplicationclientID
Applicationclientsecret
The Directory/TenantID can be found under Azure Active Directory:
The ApplicationclientID can be found under your App registration:
The Applicationclientsecret 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 win-acme for the first time.
Note
You must replace {{acme-directory-url}}, {{Key-vault-name}}, {{Name-of-cert-in-azure}}, {{Hostname}},
{{Directory/tenantid}}, {{Applicationclientid}} and {{Applicationclientsecret}} to match your configuration.
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.
Activate the agent in TrustView
Follow the steps described here, but it can be found inside TrustView under the Automation menu section.
Now the activated certificate should be in the Azure Key Vault under Certificates.
Find the line that specifies the port and adjust it:
port=kwargs.pop('port',443)
There are changes that need to be made to the following 3 files:
All 3 are located in the /usr/local/lib/python3.9/dist-packages/certbot_bigip directory.
Download these modified files below and replace them with the original files in the directory.
Change the certificate issuer to LetsEncrypt or another issuer under the relevant Automation agent, by the Certificateissuer dropdown menu.
Note
If Let’s encrypt is used as certificate issuer, there are some limitations on the renewal rate of certificates, see Let’s encrypt certificate rate limits.
Setup DNS integration
To get Let’s Encrypt certificates issued, they need to be validated with a DNS challenge, which happens through the DNS integration in TrustView.
See DNS integration for details.
This example renews a single certificate and deploys it to the F5 BIG-IP.
The crontab above is set to run twice a day (every 12 hour). So every day it checks if a certificate needs to be renewed and 30 days before expiry, the renewal process
will begin automatically.
To configure when the crontab is run, you can use this crontab generator.
Important
It is recommended to run each line in the crontab outside the crontab in the terminal once, both to test for any error of the renewal process, but also
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. -nnon-interactive will show logging in the terminal
and -qquiet will log and show nothing, which is recommended when run inside a crontab.
Set password in environment variable
This will ensure that passwords are not displayed in cleartext within the crontab or when used as part of a command.
Tip
This can also be used for usernames and other variables that you do not want to show as cleartext.
Open the .bash_profile file:
nano.bash_profile
Note
You can use whatever text editor you prefer, in this example nano is used.
Set the environment variables inside the .bash_profile file:
exportPASSWORD="my_password"
Save the file and restart the terminal, or logout from the user account and then login again,
to use the new changes to the environment variables.
PASSWORD can now be used in the Certbot command instead of using the cleartext version of the password.
Important
Check your OS, in some cases ~/.profile is used as default for environment variables, but can be overridden if you create a .bash_profile file.
11. Use win-acme to automatically issue and renew the certificate on ADFS
To see the token-signing and token-decryption certificate expiry on the ADFS, run these commands and look for the [NotAfter] timestamp.
The certificate for which the IsPrimary value is set to True is the certificate that ADFS is currently using.
Initial run of win-acme
You can use certificates from ADCS, Entrust, DigiCert, GeoTrust and Let’s Encrypt by selecting the corresponding certificateissuer
under the automation agent.
Remember to activate the Automation agent in TrustView after you run win-acme the first time.
Tip
Remember to change {{acme-directory-url}}, {{Hostname}} and {{Cert-path}} where you want your certificates to be stored, to match your configuration.
To locate the acme-directory-url, see.
Configure script
If you are using a certificate from one of the certificate issuers instead of a self-signed certificate,
you can use the script.
Download and use this PowerShell script, as a starting point for your configuration adfs.ps1
12. Automation of certificate renewal on Palo Alto firewall using Certbot
Setup and installation
Requirements:
Linux-based container or virtual machine with reachability to the Palo Alto firewall management interface
The example is shown with DigiCert certificates, but can be used with Entrust, 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 - Certificateissuer dropdown menu. With DigiCert, GeoTrust and Entrust certificates
we need to enable automation from our side, in that case contact our Support to let us know.
Let’s Encrypt certificates requires a DNS integration to be setup in TrustView
ADCS certificates requires the installation of the ADCS module and a specific CRL flag to be set on the CA
Entrust, GeoTrust and DigiCert, requires 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:
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.
Setup 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 for 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.
Setup crontab
To setup the automation for certificate retrieval and deploy script, you can use a crontab to schedule when to run the renewal and deployment process.
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 hour). 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 for any error of the renewal process, but also
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. -nnon-interactive will show logging
in the terminal and -qquiet will show nothing, which is recommended when run inside a crontab.
13. Use win-acme to automatically issue and renew the certificate in Java KeyStore
If you want to renew certificates on a Java KeyStore, it can be done with the ACME client - win-acme and a script that is run after
the certificate retrieval in TrustView.
Download win-acme and run this command to set up the automation agent inside TrustView:
Go to the settings.json file and look for the following settings:
RenewalDays [Default: 55] - The number of days to renew a certificate after.
StartBoundary [Default: “09:00:00”] - Configures start time for the scheduled task.
RandomDelay [Default: “04:00:00”] - Configures random time to wait for starting the scheduled task. This spreads the load on the servers and thus prevents users from getting TooManyRequests errors.
1.7. 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 Activationtemplates page.
Adding a new activation template
Click Agents
Click Activationtemplates
Click Add
Fill out the fields
Name the template
Choose to enable the template (can be disabled after creation, if needed)
List the subnets that matching ACME clients are allowed from, e.g. 192.168.0.0/24,10.0.0.0/8
Enter a regular expression (Regex) that must match all the DNS hostnames, requested by the ACME client, e.g. .*\.trustskills.com
Select the issuer and additional information, related to the selected issuer if required (such as the certificate type and organizational information)
Click Create
Tip
Here is a simple regex that matches the hostname example.com:
^example\.com$
But other examples can be found and tested here here.
All ACME clients require an ACME Directory URL as a parameter, to allow the client to use
the ACME Server endpoint exposed by TrustView. The ACME Directory URL is unique for
each TrustView instance. In TrustView, click on the menu item Agentclientinfo
under the AutomationAgents in the left menu. The ACME Directory URL is listed on this page:
Automation agent activation
After the initial execution of the ACME client, TrustView has registered that a
new Automation agent has connected. To allow the Automation agent to issue certificates,
you need to activate the Automation agent. This requires a few simple steps:
Click Newagents in the Agents section in the left menu, to list all automation agents pending activation
Click on the automation agent that you want to activate, to view the details of the automation agent
Select the certificate issuer, type and additional details, depending on the certificate type on the details page
Click Update to save all your changes (should be done before activating the agent)
Click Activate to activate the automation agent and get it to run its automation cycle
If using the Windows Connector for automation, you may run into an error asking you to set your current TLS version to a specific minimum version.
Setting the TLS version is not recommended by Microsoft: Microsoft best practices for TLS, but can be done if needed.
If you want to change it to TLS version 1.2, it can be done by adding this to the Windows Connector script, downloaded from TrustView:
To automate with SCEP, a client that supports the SCEP protocol is required. This means that win-acme and Certbot cannot be used, since they are
clients used with the ACME protocol.
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:
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.
In TrustView, go to Agents in the left menu and click AddSCEP in the toolbar, to create a SCEP automation agent.
Once the agent has been created, a Sharedsecret will automatically be generated and be available for you to use
in a command for your SCEP client, of your choice.
Enter a name for the SCEP agent and fill out the IPsubnets and Hostnamematcher.
Lastly select a Certificateissuer and click Update to activate the agent.
Important
Save the Sharedsecret, as it is required for connecting to the SCEP server, which in this instance is TrustView.
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 depends 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-urlhttps://trustview-instance-url/scep-cn"domain.example.com"-challenge"=i8Fy_!MfdgSEs1F"-private-key"C:\temp\privatekey.key" 2level=infots=20XX-XX-31T13:27:00.0206502Zop=GetCACerterror=nulltook=179.674ms 3level=debugts=20XX-XX-31T13:27:00.0248159Zmsg=cacertlistcount=3 4level=debugts=20XX-XX-31T13:27:00.026347Zmsg=cacertlistnumber=0rdn="CN=EndEntity,O=Organization,L=City,ST=State,C=US"hash_type=SHA-256hash=e4505b4c6bc3070fd8a12d60e7b3ae250021d0632a551b8bb57c0a37a2d30bab 5level=debugts=20XX-XX-31T13:27:00.0264065Zmsg=cacertlistnumber=1rdn="CN=IntermediateCA,O=Organization,L=City,ST=State,C=US"hash_type=SHA-256hash=4fce3213e58c9c4b0c4f733358f16e5211e2ee2efa1ec9104ab324f7943d05a0 6level=debugts=20XX-XX-31T13:27:00.0264065Zmsg=cacertlistnumber=2rdn="CN=RootCA,O=Organization,L=City,ST=State,C=US"hash_type=SHA-256hash=a04ab5ffd3f0ff4efed89380f7a47fc6b2a960ea374569fec36e0a9739af74b4 7level=debugts=20XX-XX-31T13:27:00.0275331Zmsg="creating SCEP CSR request"transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM="signer_cn="SCEP SIGNER" 8level=infots=20XX-XX-31T13:27:00.0618626Zop=GetCACapserror=nulltook=32.6128ms 9level=infots=20XX-XX-31T13:27:00.3175644Zop=PKIOperationerror=nulltook=255.3966ms10level=debugts=20XX-XX-31T13:27:00.3180724Zmsg="parsed scep pkiMessage"scep_message_type="CertRep (3)"transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM="11level=infots=20XX-XX-31T13:27:00.3191155ZpkiStatus=PENDINGmsg="sleeping for 30 seconds, then trying again."12level=infots=20XX-XX-31T13:27:30.6087161Zop=PKIOperationerror=nulltook=289.2402ms13level=debugts=20XX-XX-31T13:27:30.6098253Zmsg="parsed scep pkiMessage"scep_message_type="CertRep (3)"transaction_id="HbP2v8UTin4wY0BfT7CmGMs33BM="14level=infots=20XX-XX-31T13:27:30.6098253ZpkiStatus=SUCCESSmsg="server returned a certificate."15level=debugts=20XX-XX-31T13:27:30.6123552Zmsg="decrypt pkiEnvelope"ca_certs=316PS C:\temp\scepclient-windows-amd64-v2.2.0>
Note
In the example above, the -challenge refers to the value of Sharedsecret from the detail page, for the SCEP automation agent in TrustView.
