Certificate-Based Agent Authentication
    • Dark
    • PDF

    Certificate-Based Agent Authentication

    • Dark
    • PDF

    Article summary

    You can enable tighter control over how the ControlUp Agent communicates with the ControlUp Console and ControlUp Monitors. The procedure below prevents other machines from accessing the agent unless they have been authorized via a digital certificate. This is the highest level of security you can apply to the communication between the ControlUp Console and Monitors to the ControlUp Agents.

    You can read more about ControlUp Agent Security Best Practices and different configuration options.


    • ControlUp version 8.7 or higher
    • *.PFX certificate 
    • *.CER certificate 
    • GPO template to deploy the settings on the agent side.
      You can create your own GPO or use the attached zip file which contains a template for both this method of authentication and the ACL method described here.

    Create the Certificates

    You should designate a trustworthy member of your organization as the certificate authority administrator. This administrator should provide the public key and private key certificates.

    When creating the certificates, consider the following:

    • The supported bit keys are 2048/4096.
    • When a certificate is created, an expiration date for it is set. It is important to keep this in mind for future renewals.
    • When renewing the certificate, the thumbprint must be replaced in the GPO deploying to the agents and also on the monitor/console machines.
    • Template can be “WebServer”.
    • Intended Purposes can be “Server Authentication”
    • Certificate location must be under Local Computer > Trusted Publishers.
    • Signature algorithm can be secured as needed.

    Run a PowerShell Script to Configure the ControlUp Console and Monitor Machines 

    The steps to configure the ControlUp Console and ControlUp Monitor machines can be accomplished by running the PowerShell script Assign auth certificates to CU that is attached to this article as a text file. 

    If you want to understand the manual steps behind this script, see Certificate-based Agent Authentication - Manual Configuration on Console & Monitor Machines.

    Additional prerequisites and notes about running the script

    • You must have remote access from the machine where you are running the script to all the console and monitor machines where you are applying the certificate. You can use the -credential parameter described below to ensure that the account you specify has remote access to all the machines. 
    • You can use the script to either access a certificate that's already installed in the machine or specify a file for importing a certificate.
    • If using the -copyCertificateLocally parameter described below, the machine running the script must have read access to the certificate specified in the -certificatePath parameter. 
    • Requires PowerShell version 3 or higher on the machine running the script.

    Script parameters

    The following is a list of the script parameters and their descriptions:


    Path to the .pfx certificate file to import. Can be a folder if there is only one .pfx file contained in the folder.


    Regular expression to match the name of an existing installed certificate if you want to use that existing certificate rather than importing one from a file.


    Password for the private key in the .pfx certificate.


    Password for the private key in the .pfx certificate as a secure string.


    A comma separated list of console and monitor machines you want to apply the certificate.

    If none is specified or the computersFile parameter is not used, the certificate is applied only onto the local machine.


    A path and name of the text file containing one machine per line. Blank lines and those starting with # are ignored as are any characters like space or # after the computer name.

    Use this parameter or the computers parameter to identify the machines where to apply the certificate. If not specified and the computers parameter is not used, the certificate is applied only onto the local machine.


    Copy the certificate file specified by the -certificatePath parameter to the %temp% folder on the remote machine and delete the copy after import.


    PSCredential object to use for the PS remoting. If you assign a $null value to this parameter, while running the script you are prompted to enter the PowerShell remoting credentials.

    If you don't use this parameter, you must have remote access to the machines you are applying the certificate.


    Use SSL for PS remoting.


    Do not restart the ControlUp monitor service if present.


    Use the specified port for PS remoting rather than the default.

    Use case examples of the script

    1. Configure the already existing certificate containing *.madonna.local in the subject for use by ControlUp on machines glcumonitor01 and glcumonitor02:

      & '.\Assign auth certificates to CU.ps1' -certificateSubject '*.madonna.local' -computers glcumonitor01,glcumonitor02
    2. Configure the already existing certificate containing *.madonna.local in the subject for use by ControlUp on the local machine:

      & '.\Assign auth certificates to CU.ps1' -certificateSubject '*.madonna.local'
    3.  Prompt for credentials to use for remoting to machines to apply the certificate. Use this parameter when the account running the script does not have PowerShell remoting permissions. Then configure the already existing certificate containing *.madonna.local in the subject for use by ControlUp on the local machine:

      & '.\Assign auth certificates to CU.ps1' -certificateSubject '*.madonna.local' -credential $null
    4. Import the certificate from the file c:\temp\controlup.pfx then copy it to each machine specified in the file C:\temp\cucertmachines.txt, one entry per line representing a console or monitor machine. Then import the certificate into that computer's personal certificate store and configure it for use by ControlUp.

    Verify the Certificate on the ControlUp Console Machines

    Once you have completed running the script, restart the ControlUp Real-Time Console. When you log into the console, you should see a Certificate icon displayed at the bottom of the console window.

    You should repeat this for every machine running the ControlUp Real-Time Console.

    Verify the Certificate on the ControlUp Monitor Machines

    The machines running the ControlUp Monitors can be verified by checking the Registry Editor to see that the keys were imported to the machine and include the following:

    If you want to verify the communication to the monitor machine with a certificate, you can use a tool like log4net. Within the data the log supplies, you should see the following among the log lines:

    Client certificate read
    Enabled=True Thumbprint=<thumbprint value> key=HKEY_LOCAL_MACHINE
    Applying client certificate found on HKLM
    The client certificate was loaded

    To stop the logging, stop the monitor service and remove the file that creates the logs (e.g. log4net).

    Configure the ControlUp Agent Machines

    We recommend deploying the agent certificate and registry values via a GPO. The steps below describe how to install the certificate and registry values manually for testing purposes. 

    Both the manual setup and via a GPO require the public key (e.g. *.cer file). Each certificate should be stored in the Trusted Publishers certificate store of the local machine in scope.

    The ControlUp Agent supports multiple trusted certificates that can identify authorized consoles and monitors.

    Apply Public Key Certificate Manually to the Machines Running the ControlUp Agent

    1. Copy the public key certificate file (.cer) to the Trusted Publishers directory in the machine running the ControlUp Agent.
    2. On the agent machine, right-click the file and select Install Certificate. The Certificate Import Wizard opens.
    3. Select Local Machine and click Next.
    4. Select Place all certificates in the following store.
    5. Click Browse to select the Trusted Publishers directory and click Next.
    6. Click Finish, and the Certificate Import Wizard confirms that the import was successful.

    Configure Registry Key on the ControlUp Agent Machine

    For the agent to start enforcing client-side certificate authentication, a registry configuration is required. The registry key should be configured under the HKLM registry hive. This configuration can be part of a GPO.

    You can create your own GPO or use the attached zip file which contains a template for both this method of authentication and the ACL method described here.

    Here is the manual procedure you can use for testing.

    1. Open the Registry Editorand go to: HKLM/SOFTWARE/Policies/Smart-X/ControlUp/Agent/TrustedClients
      Missing keys must be created manually.
    2. Create a DWORD value named Enabled and assign it the value of 1.
    3. Create a Multi-String value (REG_MULTI_SZ) named Certificates. This key must contain all of the trusted certificates' thumbprints.
      The added key should look something like this:
      Your ControlUp Agent will now communicate with only those ControlUp Consoles and ControlUp Monitor machines that can be authenticated by their private key certificates.

    Enforce Certificate-Based Authentication 

    From version 8.2.5 and higher, you can enforce the use of this feature on the agent machine if you use the MSI installer to install the agents on monitored machines.

    Param name: CERTONLY
    Usage: CERTONLY=True
    Usage example:   Agentinstaller.msi CERTONLY=True 

    We recommend adding this parameter to enforce using certificate-based authentication. This means that the key-pair authentication that comes default from ControlUp for version 8.2.5 is not used but your own private/public certificates are used to authenticate communication between the agent and console and monitor machines.

    Was this article helpful?