Install the Ploy Connector on Windows

Install the Ploy Connector on Windows by downloading the release ZIP, extracting it to C:\Program Files\Ploy\Connector, provisioning a gMSA, and registering the connector as a Windows service.

Prerequisites

• Domain-joined Windows Server 2019 or later.

• PowerShell 5.1 or later, running as Administrator on the connector host.

• The RSAT AD PowerShell module on the host where you will run New-ADServiceAccount — typically a domain controller.

  Install-WindowsFeature RSAT-AD-PowerShell   # on a Server DC

• Outbound HTTPS (port 443) from the connector host to api.joinploy.com.

• A bearer key from the Ploy admin UI (format ploy_ct_…).

Download and extract

1. Download ploy-connector-<version>-windows-amd64.zip from the Ploy console.

2. Extract the contents into C:\Program Files\Ploy\Connector\. The folder should contain:

   • ploy-connector.exe

   • config.example.yaml

Provision a Group Managed Service Account (gMSA)

A gMSA is an AD-managed identity whose password rotates automatically and never needs to be stored on the host. The connector authenticates to AD as this identity.

Create a KDS root key

If your forest does not already have one, run this once on a domain controller:

Add-KdsRootKey -EffectiveTime ((Get-Date).AddHours(-10))

Create the gMSA

Run on a domain controller as a Domain Admin. Replace CONNECTORHOST with your connector host's computer name (the trailing $ is required — it identifies the computer object, not a user):

New-ADServiceAccount -Name ploy-connector -DNSHostName ploy-connector.corp.example.com -PrincipalsAllowedToRetrieveManagedPassword "CONNECTORHOST$"

Install the gMSA on the connector host

On the connector host, as Administrator:

Install-ADServiceAccount ploy-connector
Test-ADServiceAccount ploy-connector    # must return True

If Test-ADServiceAccount returns False, the host computer object is usually missing from PrincipalsAllowedToRetrieveManagedPassword. Re-run the gMSA creation step with the correct computer name.

Grant AD permissions

In standard AD configurations, authenticated users already have read access to user, group, and OU objects, so the gMSA inherits that by default. If your environment hardens the directory (List Object mode or restricted ACLs), ensure the gMSA can Read on user, group, organizationalUnit, and container objects under your base_dn.

Write access is needed only when specific features are enabled. Rather than delegate group by group, scope the rights to the OU subtree that holds the users and groups Ploy manages, and let inheritance carry them inside. Run the following on a DC as a user who can edit that OU's ACL:

Import-Module ActiveDirectory

$gmsa   = "ploy-connector"
$ouPath = "AD:\OU=Ploy-Managed,DC=corp,DC=example,DC=com"

$sid = (Get-ADServiceAccount $gmsa).SID

$userObj    = [GUID]'bf967aba-0de6-11d0-a285-00aa003049e2'
$groupObj   = [GUID]'bf967a9c-0de6-11d0-a285-00aa003049e2'
$memberProp = [GUID]'bf9679c0-0de6-11d0-a285-00aa003049e2'
$allGuid    = [GUID]'00000000-0000-0000-0000-000000000000'

$Allow    = [System.Security.AccessControl.AccessControlType]::Allow
$Desc     = [System.DirectoryServices.ActiveDirectorySecurityInheritance]::Descendents
$ScopeAll = [System.DirectoryServices.ActiveDirectorySecurityInheritance]::All

$acl = Get-Acl -Path $ouPath

# group_management: write the 'member' attribute on groups in the subtree
$acl.AddAccessRule((New-Object System.DirectoryServices.ActiveDirectoryAccessRule(
    $sid,
    [System.DirectoryServices.ActiveDirectoryRights]::WriteProperty,
    $Allow, $memberProp, $Desc, $groupObj)))

# user provisioning: create and delete user objects in the subtree
$acl.AddAccessRule((New-Object System.DirectoryServices.ActiveDirectoryAccessRule(
    $sid,
    [System.DirectoryServices.ActiveDirectoryRights]'CreateChild,DeleteChild',
    $Allow, $userObj, $ScopeAll)))

# user provisioning: full control over the user objects themselves
$acl.AddAccessRule((New-Object System.DirectoryServices.ActiveDirectoryAccessRule(
    $sid,
    [System.DirectoryServices.ActiveDirectoryRights]::GenericAll,
    $Allow, $allGuid, $Desc, $userObj)))

Set-Acl -Path $ouPath -AclObject $acl

The first rule is enough for group management. The two user-object rules are needed only when the connector provisions accounts. Omit them for a read-only or group-only deployment. If managed users and groups live under different OUs, run the relevant blocks against each OU path.

Configure the connector

The service reads C:\ProgramData\Ploy\Connector\config.yaml by default.

1. Create the config directory:

   New-Item -ItemType Directory -Force -Path "C:\ProgramData\Ploy\Connector"

2. Copy the example and edit it:

   Copy-Item "C:\Program Files\Ploy\Connector\config.example.yaml" `
             "C:\ProgramData\Ploy\Connector\config.yaml"
   notepad "C:\ProgramData\Ploy\Connector\config.yaml"

Fill in at least:

• backend.key — your bearer key (or use env://PLOY_CONNECTOR_KEY).

• integrations.<slug>.credentials.url — your DC's LDAPS URL.

• integrations.<slug>.credentials.base_dn — your domain root DN.

If you are sourcing the bearer key from an environment variable, set it at machine scope so the service sees it:

[Environment]::SetEnvironmentVariable('PLOY_CONNECTOR_KEY', 'ploy_ct_...', 'Machine')

Machine-scope environment variables apply only to new processes, so restart the service (see the next section) after changing one.

Install and start the service

From an elevated PowerShell in the connector directory:

cd "C:\Program Files\Ploy\Connector"
.\ploy-connector.exe install-service -service-account "CORP\ploy-connector$"
Start-Service PloyConnector
Get-Service PloyConnector    # Status should be Running

Replace CORP with your domain's NetBIOS name. The trailing $ is required for gMSAs. The service is registered with auto-start and survives reboots.

Verify the installation

Check three places to confirm the connector is healthy:

1. In the Ploy admin UI, go to Integrations → Connectors. Within about 30 seconds the connector reports as online with a recent heartbeat (it posts a health report every 30 seconds).

2. Tail the connector log file:

   Get-Content -Wait -Tail 50 "C:\ProgramData\Ploy\Connector\logs\connector.log"

   A healthy startup shows connector starting, then manifest registered, followed by periodic scan completed lines.

3. Open Windows Event Viewer → Applications and Services Logs → Ploy Connector. Errors land here even if the log file path is unreachable.

Update the connector

Releases are drop-in replacements:

Stop-Service PloyConnector
Copy-Item .\ploy-connector.exe "C:\Program Files\Ploy\Connector\" -Force
Start-Service PloyConnector

Config and state persist across upgrades.

Uninstall the connector

.\ploy-connector.exe uninstall-service

# Optionally remove state and config:
Remove-Item -Recurse "C:\ProgramData\Ploy\Connector"

# Optionally remove the gMSA from AD (run on a DC):
Remove-ADServiceAccount ploy-connector

Password-based authentication

Use this fallback only if your environment cannot use a gMSA.

In C:\ProgramData\Ploy\Connector\config.yaml, set auth: simple and supply bind_user and bind_password. The service can then run as LocalSystem; omit -service-account from the install command.

We strongly recommend reading the password from an environment variable rather than embedding it:

bind_password: env://AD_BIND_PASSWORD

Set the variable at machine scope (see the configuration section), then restart the service.

Corporate proxy and internal CAs

The connector honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables (machine-scope). The http://user:pass@proxy:8080 form is supported.

For internal CAs, set tls.ca_bundle in config.yaml to a PEM file path. Use tls.ca_bundle_append: true to add it to the system root store rather than replace it.

Troubleshooting