Docs / Certificates / PowerShell Agent

PowerShell Auto-Deploy Agent

The Albaspot PowerShell agent runs as a Windows Scheduled Task on your RDS server. Every six hours it polls the Albaspot API, and when a renewed certificate is available it downloads, imports, and configures it automatically — no manual steps required.

Installation

  • →Download the installer — open the certificate detail page in Albaspot and click Download PowerShell Installer. The script is pre-configured with the correct API endpoint and agent token for that certificate.
  • →Run as Administrator — right-click the downloaded .ps1 file and choose Run with PowerShell (Administrator), or run it from an elevated PowerShell prompt. Administrator rights are required to register the Scheduled Task and access the Windows certificate store.
  • →One-time setup — the installer registers the Scheduled Task, stores the agent token securely, and performs an immediate first poll to import the current certificate. No further interaction is needed.

Agent token

Each certificate has a unique agent token — a per-certificate bearer token visible on the certificate detail page under the PowerShell Installer section. The token is embedded automatically in the downloaded installer script. It authenticates the agent's API calls and scopes access to only that certificate's data. Do not share this token or commit it to source control.

What the agent does on each run

  1. 1Poll the API — the Scheduled Task fires every 6 hours and calls GET /api/v1/agent/certificate with the bearer token to check whether a newer certificate version is available.
  2. 2Early exit if unchanged — if the certificate has not been renewed since the last deployment, the agent exits immediately without making further changes. This makes every run idempotent.
  3. 3Download PFX — when a renewed certificate is detected, the agent downloads the PFX file from GET /api/v1/agent/certificate/pfx.
  4. 4Import to Windows certificate store — the PFX is imported using Import-PfxCertificate into the Local Machine store, making it available to all Windows services.
  5. 5Configure the RDS listener — the agent updates the Remote Desktop Services listener to use the new certificate via the CIM class Win32_TSGeneralSetting, binding the new thumbprint to the RDS session host.
  6. 6Remove old certificates — any previous certificates for the same domain that are no longer in use are removed from the store to keep it clean.
  7. 7Acknowledge and log — the agent calls POST /api/v1/agent/certificate/acknowledge to confirm successful deployment. All actions are written to the Windows Event Log under the Albaspot source for easy auditing.

Agent last-seen badge

Each successful API poll updates the agent's last-seen timestamp. This is visible as the Agent badge on both the certificates list and the certificate detail page. If the badge shows Not seen or the timestamp is older than expected, check that the Scheduled Task is enabled and that the RDS server has outbound HTTPS access to the Albaspot API.

API endpoints used by the agent

  • →GET /api/v1/agent/certificate — returns current certificate metadata including version and renewal state.
  • →GET /api/v1/agent/certificate/pfx — streams the PFX file for the latest certificate version.
  • →GET /api/v1/agent/certificate/pem — streams the PEM bundle (if needed for additional configuration).
  • →POST /api/v1/agent/certificate/acknowledge — confirms successful deployment and updates the last-seen timestamp.

All requests use the Authorization: Bearer <agent_token> header. No other credentials are required.

← Certificate Detail Auto-Renewal & Notifications →