windows_certificate
Experimental. A certificate file on a Windows host, imported into a certificate store: a CA’s .cer into Root, or a server’s .pfx, with its private key, into My for IIS.
Experimental. New, and tested on GitHub’s Windows Server 2022 and 2025 runners, not yet on an Azure server. See Windows readiness.
Use windows_certificate to import a certificate file into one of a Windows host’s certificate stores: your internal CA’s certificate into Root, or a web server’s .pfx, private key and all, into My for IIS. It’s the Import-Certificate or Import-PfxCertificate you’d otherwise run by hand, and a plan shows whether the certificate is still there.
Example usage
Section titled “Example usage”Trust an internal CA on every server:
step "corp_ca" { windows_certificate { path = "C:\\certs\\corp-root-ca.cer" store_name = "Root" }}A server certificate with its private key, for IIS. Give the password from an ephemeral variable, so it stays out of state and plan files:
step "web_cert" { windows_certificate { path = "C:\\certs\\www.pfx" store_name = "My" password_wo = "use-an-ephemeral-variable-here" }}Put the file on the host first, with a windows_file step.
Arguments
Section titled “Arguments”| Name | Type | Required | Description |
|---|---|---|---|
on_remove |
string | No | What happens on the host when this resource is removed: “forget” (default) leaves the certificate in the store, “delete” takes it out. The file stays either way. |
password_wo |
string | No | Write-only: a .pfx’s password, never kept in state or plan files. |
path |
string | Yes | The file on the host, ending in .cer, .crt, .der, .pfx or .p12, such as C:\certs\web.pfx. A .pfx or .p12 is imported with its private key. |
state |
string | No | “present” (default), or “absent” to take the certificate out of the store. |
store_location |
string | No | “LocalMachine” (default) or “CurrentUser”, the account Conn3x logs in as. |
store_name |
string | Yes | The store, such as My (personal, where IIS looks), Root, CA, TrustedPeople or WebHosting. |
Read-only attributes
Section titled “Read-only attributes”Conn3x sets these; reference them as conn3x_windows_certificate.<circuit>__<step>["<host>"].<name>.
| Name | Type | Description |
|---|---|---|
file_sha256 |
string | The file’s SHA-256 at the import. A different file at path, such as a renewed certificate, plans a new import. |
in_sync |
bool | Whether the store had the certificate, and the file was still the one imported, at the last refresh. |
revision |
string | Changes each time Conn3x changes this on the host. Handlers watch it. |
thumbprint |
string | The imported certificate’s thumbprint, which a refresh looks for in the store. For a .pfx with its chain, the one with the private key. |
A step lowers to the conn3x_windows_certificate resource, one instance per host, and connects with its circuit’s ssh block.
How it works
Section titled “How it works”Applying. Conn3x imports the file into store_location and store_name: a .pfx or .p12 with Import-PfxCertificate, its private key marked not exportable, and anything else with Import-Certificate. It records the certificate’s thumbprint and the file’s file_sha256. For a .pfx that brings its chain with it, the thumbprint is the certificate with the private key.
The password. password_wo goes to the host on standard input, never on a command line, and never into state or a plan file. A wrong password fails the step without repeating it.
Reading. On every plan, Conn3x looks for the recorded thumbprint in the store, and hashes the file if it’s still there. in_sync is true when the certificate is in the store, with its private key for a .pfx, and the file is the one imported. Removing the file after the import, as many do with a .pfx, is fine.
Renewal. Put the renewed file at the same path, and the next plan sees a different file and imports it. The old certificate stays in the store, since a site may still be bound to it; take it out once nothing uses it.
Changes. Changing state updates the store in place. Changing path, store_location or store_name replaces the step.
Removal
Section titled “Removal”on_remove = "forget", the default, leaves the certificate in the store. on_remove = "delete" takes it out by its thumbprint. The file stays either way.