Adding Windows Servers to CertMS

Overview

CertMS can automatically discover and monitor certificates on Windows servers through a lightweight PowerShell agent. The agent runs as a scheduled task, scanning for certificates every 6 hours and reporting back to your CertMS instance. This process can be deployed at scale using SCCM, Group Policy, or other enterprise deployment tools.

Prerequisites

Before adding Windows servers, ensure you have:

  • Administrative access to the target Windows server(s)
  • PowerShell execution permissions on the server(s)
  • Network connectivity between the server(s) and your CertMS instance
  • Appropriate permissions in CertMS to create API keys

Step-by-Step Configuration

Step 1: Create API Key for Server Monitoring

The Windows agent requires an API key to authenticate and communicate with CertMS.

  1. In the left-hand navigation menu, click the Settings dropdown
  2. Select API Keys
  3. Review any existing API keys

Create New API Key

  1. Click Create New API Key
  2. Complete the API key configuration:
Field Configuration
Name Descriptive name (e.g., Windows Server Agent API Key)
Description Optional (e.g., API key for Windows server certificate monitoring)
Roles ✅ Servers Admin (required)
✅ Cert Admin (required)
Expiration Date Set based on your security policy
Active ✅ Checked (default)
  1. Click Create API Key

Save Your API Key

Critical

This is the only time you can view the complete API key. Copy and save it in a secure location immediately — you will need it for every server you onboard.

Best Practice: You can use one API key for all Windows servers, or create separate keys per server group depending on your security requirements.

Step 2: Download the Windows Agent

  1. In the left-hand navigation menu, click Servers
  2. Locate the Download Agents dropdown button
  3. Select Windows Agent from the dropdown
  4. The PowerShell script will download to your computer
  5. Save the script somewhere accessible for deployment

Step 3: Deploy Agent to Target Server

Copy Script to Server

  1. Copy the downloaded PowerShell script to the target Windows server
  2. Place it in a temporary location (e.g., C:\Temp\)

Open Elevated PowerShell

  1. Right-click PowerShell or Windows PowerShell
  2. Select Run as Administrator
  3. Navigate to the directory containing the script

Step 4: Install the Agent

Run the Installation Command

Execute the PowerShell script with the required parameters:

.\windows_agent.ps1 -Install -ApiUrl "<api_url>" -ApiKey "<api_key>"

Parameter Details

Parameter Description Example
-Install Switch to install and onboard the server (no value needed)
-ApiUrl Your CertMS instance API URL https://acmecorp.certms.com/certms/api/v2
-ApiKey The API key created in Step 1 abcd1234-5678-90ef-ghij-klmnopqrstuv

Example

.\windows_agent.ps1 -Install -ApiUrl "https://acmecorp.certms.com/certms/api/v2" -ApiKey "abcd1234-5678-90ef-ghij-klmnopqrstuv"

What Happens During Installation

The installation script will:

  1. Create a certms folder on the server to store agent files and configuration
  2. Configure the agent with your API credentials
  3. Create a scheduled task that runs every 6 hours
  4. Display success messages upon completion

Step 5: Verify Server Onboarding

  1. Return to your CertMS instance
  2. Navigate to Servers in the left-hand navigation menu
  3. The newly onboarded server should appear in the servers list
  4. Verify that certificate data is being collected

Verification Timeline

Event Timing
Initial scan Trigger manually by running the scheduled task
Subsequent scans Every 6 hours automatically
Data visibility Server and certificates appear after first successful scan

Enterprise Deployment Options

The Windows agent can be deployed at scale using your existing enterprise tooling.

Option 1: SCCM (System Center Configuration Manager)

  1. Create an SCCM package with the PowerShell script
  2. Configure the installation command with your API URL and key
  3. Deploy to target server collections
  4. Monitor deployment status through the SCCM console

Option 2: Group Policy

  1. Create a Group Policy Object (GPO)
  2. Add the script as a startup or scheduled task script
  3. Configure script parameters in the GPO
  4. Link the GPO to the appropriate Organizational Units (OUs)
  5. Force a policy update or wait for the natural refresh cycle

Option 3: Remote PowerShell

  1. Use PowerShell remoting to deploy to multiple servers simultaneously
  2. Create a wrapper script to iterate through your server list
  3. Copy the agent and execute installation remotely
  4. Collect and log results

Deployment Best Practices

  • Test first — Deploy to a test server before rolling out enterprise-wide
  • Use secure credential storage — Store API keys in a vault or encrypted configuration, not plaintext scripts
  • Monitor deployment — Track successful installations and investigate failures
  • Document servers — Maintain an inventory of monitored servers
  • Schedule maintenance windows — Deploy during low-impact periods

Managing Server Monitoring

Viewing Monitored Servers

  1. Navigate to Servers in the left-hand navigation
  2. View all onboarded servers and their status
  3. Click any server to view detailed certificate information

Scheduled Task Details

Property Value
Task Name CertMS Certificate Scanner
Frequency Every 6 hours
Run As Local System account
Location Task Scheduler Library

Modifying Scan Frequency

  1. Open Task Scheduler on the server
  2. Locate the CertMS scheduled task
  3. Modify the trigger schedule as needed
  4. Save changes

Troubleshooting

Common Installation Issues

Issue Solution
PowerShell execution policy error Run Set-ExecutionPolicy RemoteSigned as administrator
API authentication failed Verify the API key is correct and has Servers Admin + Cert Admin roles
Network connectivity issues Verify firewall allows HTTPS (port 443) traffic to your CertMS instance
Script not found Confirm you're in the correct directory containing the script
Scheduled task creation failed Verify you have administrative privileges on the server

Server Not Appearing in CertMS

If a server doesn't appear after installation:

  1. Wait 10–15 minutes and check again
  2. Check the scheduled task ran successfully in Task Scheduler
  3. Verify API credentials are correct in the agent configuration
  4. Test network connectivity to your CertMS instance on port 443: powershell Test-NetConnection <certms-instance> -Port 443
  5. Confirm the API key is active and has the proper roles assigned

Security Considerations

  • Protect API keys — Store securely and limit access to authorized personnel
  • Use least privilege — API keys should only have the roles they actually need
  • Monitor key usage — Regularly review API key activity in Settings > API Keys
  • Rotate keys periodically — Update keys according to your security policy
  • Audit server access — Track which servers are being monitored
  • Secure agent files — Restrict access to the certms folder on each server

Uninstalling the Agent

To remove the agent from a server:

  1. Delete the CertMS scheduled task from Task Scheduler
  2. Remove the certms folder and its contents from the server
  3. Remove the server record from the CertMS interface

Need help? Contact support at support@certms.com.