win-acme 기반 Windows Server 인증서 자동화

win-acme(ACMEv2 클라이언트)를 사용하여 Certificate Manager ACME 기능으로 TLS 인증서를 자동으로 발급·갱신하는 방법을 설명합니다. DNS-01 챌린지 검증에 Ncloud Global DNS API를 사용하며, Windows Task Scheduler로 자동 갱신을 구성합니다.

서비스 사양

시작하기 전에

이 가이드를 진행하기 전에 다음 항목이 준비되어 있어야 합니다.

1단계: win-acme 설치 및 설정

win-acme 설치

1. win-acme 공식 릴리스 페이지에서 v2.2.9 이상의 release, trimmed, standalone, 64-bit 버전을 다운로드합니다.
2. 원하는 경로에 압축을 해제합니다.

settings.json 수정

win-acme 설치 디렉터리의 settings.json 파일을 열어 아래 두 항목을 반드시 수정합니다.

1. ACME 엔드포인트 변경

Acme 섹션의 DefaultBaseUri 값을 아래와 같이 변경합니다. win-acme 기본값은 Let's Encrypt이므로 반드시 변경해야 합니다.

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

2. RSA 키 크기 변경 (필수)

Csr 섹션을 찾아 아래와 같이 수정합니다.

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

설정 완료 후 핵심 항목은 다음과 같습니다.

2단계: DNS 훅 스크립트 준비

win-acme는 DNS-01 챌린지 수행 시 사용자가 준비한 외부 스크립트를 호출하여 DNS TXT 레코드를 생성·삭제합니다. DNS 훅 스크립트는 별도로 제공되지 않으므로 직접 작성해야 합니다. Ncloud Global DNS API를 사용하는 예시는 부록을 참조해 주십시오.

훅 스크립트 요구 사항

win-acme는 DNS-01 챌린지 시 아래 두 스크립트를 순서대로 호출합니다. 각 스크립트는 다음 역할을 수행해야 합니다.

생성 스크립트 (dns-create)
win-acme가 챌린지를 시작할 때 호출됩니다. 다음을 처리해야 합니다.

1. 전달받은 도메인에 해당하는 DNS zone을 탐색합니다.
2. _acme-challenge.<도메인> TXT 레코드를 생성합니다.
3. DNS 변경 사항을 반영합니다.
4. DNS 전파가 완료될 때까지 충분히 대기합니다. (권장: 60초 이상)

삭제 스크립트 (dns-delete)
챌린지 검증이 완료된 후 호출됩니다. 다음을 처리해야 합니다.

1. 생성 스크립트에서 만든 TXT 레코드를 삭제합니다.
2. DNS 변경 사항을 반영합니다.

스크립트 호출 인터페이스

win-acme는 스크립트를 호출할 때 아래 인수를 순서대로 전달합니다. 스크립트 작성 시 이 형식을 따라야 합니다.

NCP Global DNS API 연동 시 유의 사항

Ncloud Global DNS API를 사용하는 경우 아래 사항을 고려하여 스크립트를 작성하십시오.

• 모든 API 요청에는 HMAC-SHA256 서명 헤더가 필요합니다. 아래 세 헤더를 포함해야 합니다.

• 레코드 생성·삭제 후에는 반드시 Apply API를 호출해야 DNS에 반영됩니다.
• 와일드카드 인증서(*.example.com) 발급 시 도메인 앞의 *. 를 제거하고 zone을 탐색해야 합니다.
• 서브도메인 인증서(sub.example.com) 발급 시 _acme-challenge.sub 형태로 호스트명을 계산해야 합니다.

3단계: 인증서 발급

스크립트 준비가 완료되면 관리자 권한 PowerShell에서 아래 명령을 실행합니다. 대괄호([ ]) 항목은 실제 값으로 교체하십시오.

wacs.exe `
    --source manual `
    --host "[인증서를 발급할 도메인]" `
    --validation dnsscript `
    --dnscreatescript "[생성 스크립트 경로]" `
    --dnsdeletescript "[삭제 스크립트 경로]" `
    --store certificatestore `
    --certificatestore WebHosting `
    --installation iis `
    --siteid [IIS 사이트 ID] `
    --eab-key-identifier "[EAB_KEY_ID]" `
    --eab-key "[EAB_HMAC_KEY]" `
    --emailaddress "[담당자 이메일]" `
    --accepttos `
    --baseuri "https://acme.navercloudtrust.com/acme/directory"

주요 파라미터 설명

발급 흐름

4단계: 자동 갱신 설정

인증서 등록 후 관리자 권한 PowerShell에서 아래 명령을 실행하여 Task Scheduler 자동 갱신 작업을 등록합니다.

$action = New-ScheduledTaskAction `
    -Execute "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

등록된 작업은 매일 09:00에 실행되며 갱신 여부를 자동으로 판단합니다. 갱신이 필요한 경우 DNS-01 챌린지를 수행하고 IIS 바인딩을 무중단으로 교체합니다.

갱신 상태를 확인하려면 아래 명령을 실행합니다.

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

갱신 로그는 win-acme 데이터 디렉터리 하위 Log\log-YYYYMMDD.txt 파일에서 확인할 수 있습니다.

인증서 확인

발급된 인증서는 Windows Certificate Store의 WebHosting 저장소에 저장됩니다. 아래 방법으로 확인합니다.

# IIS 바인딩 인증서 thumbprint 확인
Get-WebBinding | Where-Object { $_.protocol -eq "https" } |
    Select-Object bindingInformation, certificateHash

# WebHosting 스토어 인증서 목록 조회
Get-ChildItem "Cert:\LocalMachine\WebHosting" |
    Select-Object Subject, Thumbprint, NotAfter, Issuer

또는 Windows 인증서 관리자 (certlm.msc) → 인증서(로컬 컴퓨터) → 웹 호스팅 → 인증서에서 확인할 수 있습니다.

EAB 키 교체

EAB 키를 교체해야 하는 경우 아래 순서대로 진행합니다. 기존 ACME 계정 파일이 남아 있으면 새 EAB 키가 무시되고 기존 계정이 재사용되므로, 반드시 계정 파일을 먼저 삭제해야 합니다.

1. 스크립트 또는 설정 파일에서 EAB 값을 새로 발급받은 값으로 교체합니다.
2. win-acme 데이터 디렉터리에서 Registration_v2, Signer_v2, *.renewal.json 파일을 삭제합니다.
3. 3단계의 발급 명령을 다시 실행합니다.

성공하면 새 계정으로 인증서가 발급되고 IIS 바인딩이 자동으로 교체됩니다. Task Scheduler 작업은 별도 수정이 불필요합니다.

수동 갱신

테스트 또는 긴급 대응이 필요한 경우 아래 명령을 사용합니다.

# 일반 갱신 (만료 조건 충족 시에만 실행)
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory"

# 강제 갱신 (조건 무관하게 즉시 실행)
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory" --force

# 상세 로그 출력하며 강제 갱신
wacs.exe --renew --baseuri "https://acme.navercloudtrust.com/acme/directory" --force --verbose

# Task Scheduler 작업 즉시 실행
Start-ScheduledTask -TaskName "win-acme daily renew"

# 등록된 renewal 목록 확인
wacs.exe --list --baseuri "https://acme.navercloudtrust.com/acme/directory"

문제 해결

로그를 확인하려면 아래 명령을 실행합니다.

Get-Content "win-acme 데이터 경로\Log\log-$(Get-Date -Format yyyyMMdd).txt" -Tail 100

보안 권고

• API 키와 EAB 키가 포함된 설정 파일은 Git 저장소나 공유 폴더에 포함하지 마십시오.
• Ncloud API 키에는 Global DNS 서비스에만 최소 권한을 부여하는 것을 권장합니다.
• win-acme 데이터 디렉터리(ACME 계정 서명 키 포함)에 대한 접근 권한을 관리자 계정으로 제한하십시오.
• 인증서 개인키가 외부에 노출되지 않도록 주의하십시오.
• win-acme 및 PowerShell을 정기적으로 최신 버전으로 유지하십시오.

부록: Ncloud Global DNS 훅 스크립트 예시

아래는 Ncloud Global DNS API를 사용하는 DNS 훅 스크립트 예시입니다.

config.ps1 — API 키 설정 파일

# ACME 서버 (변경 불필요)
$ACME_SERVER = "https://acme.navercloudtrust.com/acme/directory"

# EAB 키 — Certificate Manager 콘솔에서 발급받은 값으로 교체
$EAB_KID      = "[EAB_KEY_ID]"
$EAB_HMAC_KEY = "[EAB_HMAC_KEY]"

# NCP Global DNS API 키 — NCP IAM 콘솔에서 발급 (Global DNS 권한 필요)
$NCP_ACCESS_KEY = "[NCP_ACCESS_KEY]"
$NCP_SECRET_KEY = "[NCP_SECRET_KEY]"
$NCP_DNS_API    = "https://globaldns.apigw.ntruss.com"

# DNS 전파 대기 시간(초). 검증 실패 시 90~120으로 늘리십시오.
$DNS_PROPAGATION_WAIT = 60

# ACME 계정 이메일
$ACME_EMAIL = "[ADMIN_EMAIL]"

dns-create.ps1 — TXT 레코드 생성 훅

# dns-create.ps1 — win-acme DNS-01 생성 훅 (NCP Global DNS)
# UTF-8 BOM 인코딩으로 저장할 것

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"
    }
}

# 와일드카드 처리
$Domain = $Domain -replace "^\*\.", ""

# Zone 탐색
$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 "[오류] NCP Global DNS에서 '$Domain'에 해당하는 zone을 찾을 수 없습니다."
    exit 1
}

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

# TXT 레코드 호스트명 계산
if ($Domain -eq $zoneName) {
    $hostName = "_acme-challenge"
} else {
    $sub      = $Domain -replace "\.$([regex]::Escape($zoneName))$", ""
    $hostName = "_acme-challenge.$sub"
}

# TXT 레코드 생성
$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 "[오류] TXT 레코드 생성에 실패했습니다."
    exit 1
}

# 레코드 ID 임시 저장 (삭제 훅에서 사용)
$tmpFile = "$env:TEMP\ncp_sid_$($Domain -replace '\*','_').json"
@{ recordId = $response.recordId; domainId = $zoneId } | ConvertTo-Json |
    Set-Content $tmpFile -Encoding UTF8

# 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 레코드 생성 완료. $DNS_PROPAGATION_WAIT 초 대기 중..."
Start-Sleep -Seconds $DNS_PROPAGATION_WAIT

dns-delete.ps1 — TXT 레코드 삭제 훅

# dns-delete.ps1 — win-acme DNS-01 삭제 훅 (NCP Global DNS)
# UTF-8 BOM 인코딩으로 저장할 것

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 "[경고] 삭제할 레코드 정보를 찾을 수 없습니다."
    exit 0
}

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

# 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 레코드 삭제 완료."