Installing MS agents

Installation requirements

To install an MS agent, the following requirements must be satisfied:

  • Supported Windows server platform (2012, 2016, 2019, 2022)

  • MS Active Directory (AD)

    • (Suggested) Existing AD CS installation removed from target server

      Using an existing AD CS installation may cause configuration incompatibilities and prevent the agent from working as intended. For information on AD CS, see Active Directory Certificate Services (AD CS) Introduction.
    • Server joined to the AD domain

    • Enterprise Administrator permissions

  • Hardware:

    • CPU — 1.4GHz 64-bit (minimum)

    • RAM — 4 GB (minimum)

    • Storage — 60 GB (minimum)

  • Internet access:

    • Outbound network access to https://cert-manager.com on TCP 443

Add an MS agent to SCM

  1. Navigate to Integrations  MS Agents and click the Add icon.

    Add MS Agent
  2. In the Add MS Agent dialog, provide a name to help identify the agent.

  3. Select the organization and department to use for default enrollment requests.

  4. Click Next.

  5. Copy the installation token for use during installation.

    MS Agent Installation Token
  6. Initiate the agent download with the Windows installation package link.

    MS Agent Download
  7. Click Save.

The agent should now be listed on the MS Agents page with a status of Pending.

MS Agent Pending

Install an MS agent

  • Windows

  • Windows ( CLI )

  1. Run the bootstrap application.

    The bootstrap application will download the Windows Installer package files (MSI) from https://dist.sectigo.com as necessary. If you’re using an HTTP proxy, ensure that your OS proxy settings have been configured to allow access to https://dist.sectigo.com.
  2. Read the EULA, select I agree to the license terms and conditions, and click Install.

  3. Click Next.

  4. Read the EULA, select I accept the terms in the License Agreement, and click Next.

  5. (Optional) Specify an install location.

  6. (Optional) Select the Proxy MS Enrollment Protocols to SCM feature.

  7. Click Next, and paste the agent install token.

    If needed, you can retrieve the installation token from the Edit MS Agent dialog for your agent. This token is no longer available once the agent connects to SCM for the first time.
  8. Click Next.

  9. (Optional) Select Use Proxy and enter your proxy details based on the information provided in the following table.

    Field Description

    Proxy Host

    The hostname or IP address of your proxy server

    Proxy Port

    The port number used by your proxy server

    Proxy User

    The username for accessing the proxy server if configured to use credentials

    Proxy Password

    The password for accessing the proxy server if configured to use credentials

  10. Click Next.

  11. (Optional) Disable Enable Auto Update if you do not want the agent to automatically update to new versions.

  12. Click Next, Install, Finish, and then Close.

The agent should now be listed on the MS Agents page with a status of Connected.

MS Agent Connected
To be notified in the event that an agent is disconnected, add the MS Agent Disconnected notification.
  1. Open the Windows command prompt.

  2. In the command line, navigate to the download location of the bootstrap application.

    The bootstrap application will download the Windows Installer package files (MSI) from https://dist.sectigo.com as necessary. If you’re using an HTTP proxy, ensure that your OS proxy settings have been configured to allow access to https://dist.sectigo.com.
  3. Modify the installation command as needed.

    .\Sectigo_MS_Agent.exe /i /q PROPERTY_AUTOUPDATE=1 PROPERTY_TOKEN= PROPERTY_CA_PROXY= PROPERTY_USE_PROXY= PROPERTY_PROXY_PAC_URL= PROPERTY_PROXY_HOST= PROPERTY_PROXY_PORT= PROPERTY_PROXY_USER= PROPERTY_PROXY_PASSWORD=

    Options without an included value are ignored. The command options are outlined in the following table.

    Option Description

    /i

    Initiates installation of the agent through the bootstrap application

    /q

    Runs the installation in silent mode so no interaction is required

    PROPERTY_AUTOUPDATE

    Indicates whether the agent should automatically update

    The possible values are:

    • 1 (Yes)

    • Empty (No)

    PROPERTY_TOKEN

    The mandatory installation token

    PROPERTY_CA_PROXY

    Indicates whether the agent should act as a CA proxy

    The possible values are:

    • 1 (Yes)

    • Empty (No)

    PROPERTY_USE_PROXY

    Indicates whether you are using a proxy server

    • 1 (Yes)

    • Empty (No)

    PROPERTY_PROXY_PAC_URL

    The address of your proxy auto-config (PAC)

    This file contains your proxy configuration details and can be used instead of specifying values for the PROPERTY_PROXY_HOST, PROPERTY_PROXY_PORT, PROPERTY_PROXY_USER, and PROPERTY_PROXY_PASSWORD options.

    PROPERTY_PROXY_HOST

    The hostname or IP address of your proxy server

    PROPERTY_PROXY_PORT

    The port number used by your proxy server

    PROPERTY_PROXY_USER

    The username for accessing the proxy server if configured to use credentials

    PROPERTY_PROXY_PASSWORD

    The password for accessing the proxy server if configured to use credentials

  4. Run the modified installation command.

The agent should now be listed on the MS Agents page with a status of Connected.

MS Agent Connected
To be notified in the event that an agent is disconnected, add the MS Agent Disconnected notification.

Update an MS agent

  1. Log in to SCM.

  2. From the left-hand menu, select About.

  3. Click the Download MS Agent icon and select Windows.

  4. (Optional) If required, move the Sectigo_MS_Agent.exe file to the install location of the existing MS agent.

  5. Right-click Sectigo_MS_Agent.exe and click Install.

    The package automatically recognizes that there’s an existing version of the MS agent and initiates an update instead of a new install.

  6. In SCM, navigate to the Private Key Agent page and verify that the agent is connected and showing the correct version.

  7. Read the EULA, select I agree to the license terms and conditions, and click Install.

  8. Click Next.

  9. Read the EULA, select I accept the terms in the License Agreement, and click Next.

  10. (Optional) Specify an installation location.

  11. Click Next, Install, and Close.

  12. In SCM, navigate to the MS Agents page and verify that the agent is connected and showing the correct version.

Uninstall an MS agent

  1. Navigate to Settings  Apps & features.

  2. Search for Sectigo.

  3. Select the Sectigo MS Agent and click Uninstall.

  4. (Optional) Delete the files and logs associated with the MS agent.

    1. Navigate to C:\ProgramData\Sectigo.

    2. Delete the MS Agent folder.

      This cannot be undone. Only delete this folder if you want to completely remove all files and logs related to the MS agent.
  5. In SCM, navigate to Integrations  MS Agents.

  6. Select the agent you want to delete.

  7. Click the Delete icon.

  8. Click Delete again.

MS agent service commands

  • Proxy service

  • Discovery service

When an MS agent is installed with Proxy MS Enrollment Protocols to SCM selected, the service commands are as follows:

Command Description

Start

Start an MS agent:

sc start CertSvc

Stop

Stop an MS agent:

sc stop CertSvc

Query

Query the status of an MS agent:

sc query CertSvc

When an MS agent is installed for discovery only (without Proxy MS Enrollment Protocols to SCM selected), the service commands are as follows:

Command Description

Start

Start an MS agent:

sc start ComodoMSAgent

Stop

Stop an MS agent:

sc stop ComodoMSAgent

Query

Query the status of an MS agent:

sc query ComodoMSAgent

Custom Java Runtime Environments

In some rare circumstances the default Java Runtime Sectigo packages included with the MS agent might need to be customized. For example, this can happen if an HTTP proxy is using privately trusted certificates or requires authentication schemes that aren’t enabled by default.

  1. Open the Registry Editor application.

  2. Navigate to HKEY_Local_Machine  Software  Comodo  CCM.

  3. Right-click on CCM and select New  Multi-String Value.

  4. Rename the new registry value to be JavaOpts.

  5. Modify the Value data for JavaOpts using the information provided in the following table.

    JVM Parameter Description

    -Djavax.net.ssl.trustStore=path_to_keystore.jks

    Replaces the truststore used by the JVM when trusting SSL certificates

    Can be used if HTTP proxy uses a privately trusted certificate instead of needing to modify the JVMs truststore (cacerts)

    -Djdk.http.auth.proxying.disabledSchemes=""

    Reenables all authentication schemes when connecting to HTTP proxy

    -Djdk.http.auth.tunneling.disabledSchemes=""

    Reenables all authentication schemes when connecting to HTTP proxy using TLS

  6. Click OK.

Configure LDAPS communication with MS AD

Enable LDAPS communication between the MS Agent and MS AD as follows:

  1. Obtain an SSL certificate.

    The SSL certificate must comply with the requirements outlined by Microsoft for an LDAPS certificate. These requirements are subject to change by Microsoft at any time without notice.

  2. Run regedit.

  3. Navigate to HKEY_LOCAL_MACHINE  SOFTWARE  COMODO  CCM.

  4. Create a value of the type REG_DWORD = UseLDAPS.

  5. Specify a Data value of 0 if using LDAP, or 1 if using LDAPS.

    Since LDAPS communication imposes additional requirements, LDAP is the default communication protocol.

  6. Restart the agent using the certsrv.mcs snap-in.