Automate Windows server certificates using win-acme

Available in Classic and VPC

This section explains how to use win-acme (an ACMEv2 client) to automatically issue and renew TLS certificates using the Certificate Manager ACME feature. Use the Ncloud Global DNS API for the DNS-01 challenge validation, and configure automatic renewal using Windows Task Scheduler.

Service specifications

Before you start

Before you start this guide, you must have the following items ready.

Step 1: Install and configure win-acme

Install win-acme

1. Download the release, trimmed, standalone, 64-bit version of v2.2.9 or later from the official win-acme release page.
2. Extract the files to the desired directory.

Modify settings.json

Open the settings.json file in the win-acme installation directory and modify the following two items.

1. Modify ACME endpoint

Modify the DefaultBaseUri value in the Acme section as shown below. The default for win-acme is Let's Encrypt, so you must modify it.

"Acme": {
  "DefaultBaseUri": "https://acme.navercloudtrust.com/acme/directory"
}

2. Modify RSA key size (required)

Find the Csr section and modify it as shown below.

"Csr": {
  "Rsa": {
    "KeyBits": 2048,
    "SignatureAlgorithm": "SHA256withRSA"
  }
}

Once the configuration is complete, the key items are as follows:

Step 2: Prepare DNS hook script

When performing the DNS-01 challenge, win-acme calls an external script prepared by the user to create and delete DNS TXT records. Since a DNS hook script is not provided separately, you'll need to write one yourself. For examples of how to use Ncloud Global DNS API, see Ncloud Global DNS hook script example.

Hook script requirements

During the DNS-01 challenge, win-acme calls the following two scripts in order. Each script must perform the following roles:

Create script (dns-create)
Called when win-acme starts the challenge. It must process the following tasks:

1. Search for the DNS zone corresponding to the domain provided.
2. Create _acme-challenge.<도메인> TXT record.
3. Apply the DNS changes.
4. Wait long enough for the DNS propagation to complete. (Recommended: 60 seconds or more)

Delete script (dns-delete)
Called when the challenge validation is complete. It must process the following tasks:

1. Delete the TXT record created by the create script.
2. Apply the DNS changes.

Script call interface

When calling the script, win-acme passes the following arguments in the order: You must follow this format when writing scripts.

Precautions for Ncloud Global DNS API integration

When using Ncloud Global DNS API, keep the following points in mind when writing your script.

• All API requests must include an HMAC-SHA256 signature header. You must include the following three headers:

• After creating or deleting a record, you must call the Apply API for the change to take effect in DNS.
• When issuing a wildcard certificate (*.example.com), you must remove *. from the beginning of the domain and search for to the zone.
• When issuing a subdomain certificate (sub.example.com), you must calculate the hostname in _acme-challenge.sub format.

Step 3: Issue certificate

Once the script is ready, run the following command in PowerShell with administrator permissions: Replace the item in parentheses ([ ]) with an actual value.

wacs.exe `
    --source manual `
    --host "[Domain for which the certificate will be issued]" `
    --validation dnsscript `
    --dnscreatescript "[Create script path]" `
    --dnsdeletescript "[Delete script path]" `
    --store certificatestore `
    --certificatestore WebHosting `
    --installation iis `
    --siteid [IIS site ID] `
    --eab-key-identifier "[EAB_KEY_ID]" `
    --eab-key "[EAB_HMAC_KEY]" `
    --emailaddress "[Contact person's email address]" `
    --accepttos `
    --baseuri "https://acme.navercloudtrust.com/acme/directory"

Explanation of key parameters

Issuance process

Step 4: Set automatic renewal

After registering the certificate, run the following command in PowerShell with administrator permissions to register the Task Scheduler automatic renewal job.

$action = New-ScheduledTaskAction `
    -Execute "full path to wacs.exe" `
    -Argument '--renew --baseuri "https://acme.navercloudtrust.com/acme/directory"'

$trigger = New-ScheduledTaskTrigger -Daily -At "09:00"

$principal = New-ScheduledTaskPrincipal `
    -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest

$settings = New-ScheduledTaskSettingsSet `
    -ExecutionTimeLimit (New-TimeSpan -Hours 2) `
    -StartWhenAvailable

Register-ScheduledTask `
    -TaskName "win-acme daily renew" `
    -Action $action `
    -Trigger $trigger `
    -Principal $principal `
    -Settings $settings `
    -Force

Registered tasks run at 9:00 a.m. every day and automatically determine whether renewal is needed. If renewal is required, perform the DNS-01 challenge and replace the IIS binding without downtime.

To check the renewal status, run the following command:

Get-ScheduledTaskInfo -TaskName "win-acme daily renew" |
    Select-Object LastRunTime, LastTaskResult, NextRunTime

The renewal log can be found in the Log\log-YYYYMMDD.txt file within the win-acme data directory.

Verify certificate

The issued certificate is saved in WebHosting Store of the Windows Certificate Store. Follow the steps below to check:

# Verify IIS binding certificate thumbprint
Get-WebBinding | Where-Object { $_.protocol -eq "https" } |
    Select-Object bindingInformation, certificateHash

# View certificate list in the WebHosting Store
Get-ChildItem "Cert:\LocalMachine\WebHosting" |
    Select-Object Subject, Thumbprint, NotAfter, Issuer

Alternatively, you can check this in Windows Certificate Manager (certlm.msc) → Certificates (Local Computer) → Web Hosting → Certificates.

Replace EAB key

If you need to replace the EAB key: If an existing ACME account file remains, the new EAB key will be ignored and the existing account will be reused. Therefore, you must delete the account file first.

1. Replace the EAB value in the script or configuration file with the newly issued value.
2. Delete Registration_v2, Signer_v2, *.renewal.json files from the win-acme data directory.
3. Run the issuance command in Step 3 again.

If successful, a certificate will be issued for the new account, and the IIS binding will be automatically replaced. You don't need to modify Task Scheduler jobs.

Manual renewal

Use the commands below when testing or responding to an emergency:

# Regular renewal (performed only when expiration conditions are met)
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory"

# Forced renewal (performed immediately, regardless of conditions)
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory" --force

# Forced renewal while outputting detailed logs
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory" --force --verbose

# Run Task Scheduler jobs immediately
Start-ScheduledTask -TaskName "win-acme daily renew"

# View the list of registered renewals
wacs.exe --list --baseuri "https://acme.navercloudtrust.com/acme/directory"

Troubleshooting

Run the following command to view the log.

Get-Content "win-acme data path\Log\log-$(Get-Date -Format yyyyMMdd).txt" -Tail 100

Security advisory

• Do not include configuration files containing API keys or EAB keys in a Git repository or shared folder.
• We recommend granting the Ncloud API key only the minimum permissions limited to the Global DNS service.
• Restrict access to the win-acme data directory (which contains the ACME account signing key) to the administrator account.
• Take care to ensure that the certificate's private key is not exposed to outside parties.
• Keep win-acme and PowerShell updated to the latest versions on a regular basis.

Ncloud Global DNS hook script example

Below is an example of a DNS hook script that uses Ncloud Global DNS API.

API Key configuration file: config.ps1

# ACME server (no need to change)
$ACME_SERVER = "https://acme.navercloudtrust.com/acme/directory"

# EAB key — Replace with the value issued by the Certificate Manager console
$EAB_KID      = "[EAB_KEY_ID]"
$EAB_HMAC_KEY = "[EAB_HMAC_KEY]"

# NCP Global DNS API key — Issued by NCP IAM console (Global DNS permissions required)
$NCP_ACCESS_KEY = "[NCP_ACCESS_KEY]"
$NCP_SECRET_KEY = "[NCP_SECRET_KEY]"
$NCP_DNS_API    = "https://globaldns.apigw.ntruss.com"

# DNS propagation delay (seconds). If validation fails, increase it to 90–120.
$DNS_PROPAGATION_WAIT = 60

# ACME account email
$ACME_EMAIL = "[ADMIN_EMAIL]"

TXT record create hook: dns-create.ps1

# dns-create.ps1 — win-acme DNS-01 create hook (NCP Global DNS)
# Save using UTF-8 BOM encoding

param(
    [string]$Action,
    [string]$Domain,
    [string]$RecordName,
    [string]$Token
)

$ConfigPath = Join-Path $PSScriptRoot "config.ps1"
. $ConfigPath

function Get-NcpHeaders {
    param([string]$Method, [string]$Uri)
    $timestamp = [long]([datetimeoffset]::UtcNow.ToUnixTimeMilliseconds())
    $message = "$Method $Uri`n$timestamp`n$NCP_ACCESS_KEY"
    $hmac = New-Object System.Security.Cryptography.HMACSHA256
    $hmac.Key = [System.Text.Encoding]::UTF8.GetBytes($NCP_SECRET_KEY)
    $sig = [Convert]::ToBase64String(
        $hmac.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($message))
    )
    return @{
        "x-ncp-apigw-timestamp"    = "$timestamp"
        "x-ncp-iam-access-key"     = $NCP_ACCESS_KEY
        "x-ncp-apigw-signature-v2" = $sig
        "Content-Type"             = "application/json"
    }
}

# Wildcard processing
$Domain = $Domain -replace "^\*\.", ""

# Zone search
$zoneUri = "/v1/ncpdns/domain?page=1&size=100"
$zones = (Invoke-RestMethod -Uri "$NCP_DNS_API$zoneUri" `
    -Headers (Get-NcpHeaders "GET" $zoneUri)).domainList

$matchedZone = $zones | Where-Object {
    $Domain -eq $_.name -or $Domain.EndsWith(".$($_.name)")
} | Select-Object -First 1

if (-not $matchedZone) {
    Write-Error "[Error] The zone corresponding to ‘$Domain’ cannot be found in NCP Global DNS."
    exit 1
}

$zoneId   = $matchedZone.domainId
$zoneName = $matchedZone.name

# Calculate TXT record host name
if ($Domain -eq $zoneName) {
    $hostName = "_acme-challenge"
} else {
    $sub      = $Domain -replace "\.$([regex]::Escape($zoneName))$", ""
    $hostName = "_acme-challenge.$sub"
}

# Create TXT record
$createUri = "/v1/ncpdns/record/$zoneId"
$body = @{ type = "TXT"; host = $hostName; content = $Token; ttl = 60 } | ConvertTo-Json
$response = Invoke-RestMethod -Uri "$NCP_DNS_API$createUri" -Method POST `
    -Headers (Get-NcpHeaders "POST" $createUri) -Body $body

if (-not $response.recordId) {
    Write-Error "[Error] Failed to create TXT record."
    exit 1
}

# Temporarily store Record ID (used in the delete hook)
$tmpFile = "$env:TEMP\ncp_sid_$($Domain -replace '\*','_').json"
@{ recordId = $response.recordId; domainId = $zoneId } | ConvertTo-Json |
    Set-Content $tmpFile -Encoding UTF8

# Reflect DNS
$applyUri = "/v1/ncpdns/domain/$zoneId/apply"
Invoke-RestMethod -Uri "$NCP_DNS_API$applyUri" -Method PUT `
    -Headers (Get-NcpHeaders "PUT" $applyUri) | Out-Null

Write-Host "DNS TXT record creation complete. Waiting for $DNS_PROPAGATION_WAIT second(s)..."
Start-Sleep -Seconds $DNS_PROPAGATION_WAIT

TXT record delete hook: dns-delete.ps1

# dns-delete.ps1 — win-acme DNS-01 delete hook (NCP Global DNS)
# Save using UTF-8 BOM encoding

param(
    [string]$Action,
    [string]$Domain,
    [string]$RecordName,
    [string]$Token
)

$ConfigPath = Join-Path $PSScriptRoot "config.ps1"
. $ConfigPath

function Get-NcpHeaders {
    param([string]$Method, [string]$Uri)
    $timestamp = [long]([datetimeoffset]::UtcNow.ToUnixTimeMilliseconds())
    $message = "$Method $Uri`n$timestamp`n$NCP_ACCESS_KEY"
    $hmac = New-Object System.Security.Cryptography.HMACSHA256
    $hmac.Key = [System.Text.Encoding]::UTF8.GetBytes($NCP_SECRET_KEY)
    $sig = [Convert]::ToBase64String(
        $hmac.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($message))
    )
    return @{
        "x-ncp-apigw-timestamp"    = "$timestamp"
        "x-ncp-iam-access-key"     = $NCP_ACCESS_KEY
        "x-ncp-apigw-signature-v2" = $sig
    }
}

$Domain  = $Domain -replace "^\*\.", ""
$tmpFile = "$env:TEMP\ncp_sid_$($Domain -replace '\*','_').json"
$sid     = Get-Content $tmpFile -ErrorAction SilentlyContinue | ConvertFrom-Json

if (-not $sid) {
    Write-Warning "[Warning] The record to be deleted cannot be found."
    exit 0
}

# Delete TXT record
$deleteUri = "/v1/ncpdns/record/$($sid.domainId)/$($sid.recordId)"
Invoke-RestMethod -Uri "$NCP_DNS_API$deleteUri" -Method DELETE `
    -Headers (Get-NcpHeaders "DELETE" $deleteUri) | Out-Null

# Reflect DNS
$applyUri = "/v1/ncpdns/domain/$($sid.domainId)/apply"
Invoke-RestMethod -Uri "$NCP_DNS_API$applyUri" -Method PUT `
    -Headers (Get-NcpHeaders "PUT" $applyUri) | Out-Null

Remove-Item $tmpFile -Force -ErrorAction SilentlyContinue
Write-Host "DNS TXT record deletion complete."