PKI 시크릿 엔진과 ACME 문제 해결

PKI 시크릿 엔진과 ACME 문제 해결

Vault PKI 시크릿 엔진의 ACME 서버와 ACME 클라이언트 통합에서 발생하는 흔한 문제를 해결하는 방법을 알려드릴게요.

출처: 문서

본문

오류: ACME 기능에는 로컬 클러스터 'path' 필드 구성이 필요합니다

Vault Enterprise 클러스터의 일부 노드에서는 ACME가 작동하지만 다른 노드에서는 작동하지 않는다면, 클러스터 주소가 설정되지 않았을 가능성이 커요.

증상 (Symptoms)

Vault 클라이언트가 Performance Secondary 노드에서 ACME 구성을 읽거나(/config/acme), ACME 클라이언트가 이 노드의 디렉토리에 연결하려 하면 다음과 같은 오류가 발생해요.

ACME feature requires local cluster 'path' field configuration to be set

원인 (Cause)

대부분의 경우 클러스터 경로 오류는 클러스터 구성 파라미터에 필요한 클러스터 주소가 설정되지 않았음을 의미해요.

해결 방법 (Resolution)

각 Performance Replication 클러스터에 대해 /config/cluster의 값을 읽고 path 필드가 설정되어 있는지 확인하세요. 없으면 URL을 이 PR 클러스터의 TLS 활성 주소에서 이 마운트의 경로를 가리키도록 갱신해요. 이 도메인은 로드 밸런싱 또는 DNS 라운드로빈 주소일 수 있어요. 예를 들어:

$ vault write pki/config/cluster path=https://cluster-b.vault.example.com/v1/pki

완료되면 ACME 구성을 다시 읽고 경고가 나타나지 않는지 확인하세요.

$ vault read pki/config/acme

오류: ACME 서버에 계정을 등록할 수 없습니다

증상 (Symptoms)

외부 계정 바인딩(EAB) 없이 새 계정을 등록하면 Vault 서버가 다음과 같은 응답으로 요청을 거부해요.

Unable to register an account with ACME server

디버그 로그(certbot의 경우)에 추가 정보가 제공돼요:

Server requires external account binding.

또는 클라이언트가 서버에 잘못 접촉했다면 이런 오류가 나올 수 있어요.

The request must include a value for the 'externalAccountBinding' field

두 경우 모두 Vault가 만든 EAB 토큰으로 새 계정을 만들어야 해요.

원인 (Cause)

서버가 ACME 구성에서 eab_policy=always-required를 요구하도록 갱신되었다면, 새 계정 등록(및 기존 계정 재사용)이 실패해요.

해결 방법 (Resolution)

Vault 토큰을 사용해 원하는 디렉토리에 대한 새 외부 계정 바인딩을 가져오세요.

$ vault write -f pki/roles/my-role-name/acme/new-eab
...
directory roles/my-role-name/acme/directory
id        bc8088d9-3816-5177-ae8e-d8393265f7dd
key       MHcCAQE... additional data elided ...
...

그런 다음 이 새 EAB 토큰을 ACME 클라이언트에 전달해요. 예를 들어 certbot의 경우:

$ certbot [... additional parameters ...] \
    --server https://cluster-b.vault.example.com/v1/pki/roles/my-role-name/acme/directory \
    --eab-kid bc8088d9-3816-5177-ae8e-d8393265f7dd \
    --eab-hmac-key MHcCAQE... additional data elided ...

ACME 클라이언트에 전달한 ACME 디렉토리가 Vault에서 가져온 것과 일치하는지 확인하세요.

오류: EAB 검증 실패 (Failed to verify eab)

증상 (Symptoms)

이 Vault 서버에 대해 새 계정을 초기화할 때 ACME 클라이언트가 다음과 같은 메시지로 오류를 내놓을 수 있어요.

The client lacks sufficient authorization :: failed to verify eab

이는 클라이언트가 사용한 디렉토리와 일치하지 않는 디렉토리에서 EAB를 요청했기 때문에 발생해요.

원인 (Cause)

EAB 계정 토큰이 잘못된 디렉토리와 함께 사용되면, ACME 서버는 권한 부족에 대한 오류로 요청을 거부해요.

해결 방법 (Resolution)

요청된 EAB 토큰이 디렉토리와 일치하는지 확인하세요. /some/path/acme/directory 디렉토리의 경우 /some/path/acme/new-eab에서 EAB 토큰을 가져오세요. 나머지 해결 단계는 계정 등록 실패 디버깅과 동일해요.

오류: ACME 검증이 {challenge_id}에 대해 실패했습니다

증상 (Symptoms)

Vault 서버 로그를 보거나 ACME 클라이언트로 인증서를 가져오려 할 때 이런 오류가 발생하면:

ACME validation failed for a465a798-4400-6c17-6735-e1b38c23de38-tls-alpn-01: ...

이는 서버가 클라이언트가 수락한 이 챌린지를 검증하지 못했음을 나타내요.

원인 (Cause)

Vault가 클라이언트가 요청한 챌린지 유형(dns-01, http-01, 또는 tls-alpn-01)을 통해 서버의 신원을 검증할 수 없어요. Vault는 클라이언트가 요청한 인증서를 발급하지 않을 거예요.

해결 방법 (Resolution)

사용자 지정 DNS 리졸버 설정을 포함해 DNS가 Vault 서버 관점에서 올바르게 구성되어 있는지 확인하세요.

Vault가 관련 시스템과 통신할 수 있도록 방화벽이 설정되어 있는지 확인하세요(가능한 경우 dns-01의 DNS 서버, http-01의 대상 머신의 80 포트, tls-alpn-01 챌린지의 대상 머신의 443 포트).

오류: 클라이언트의 인증 부족: 계정 *** 상태: revoked

증상 (Symptoms)

인증서를 갱신하려 할 때 ACME 클라이언트가 다음과 같은 오류를 보고해요.

The client lacks sufficient authorization: account *** status: revoked

원인 (Cause)

수동 tidy를 실행하거나 tidy_acme=true로 auto-tidy를 활성화하면 Vault가 주기적으로 오래된 ACME 계정을 제거해요.

제거된 계정을 사용하는 클라이언트의 연결은 거부돼요.

해결 방법 (Resolution)

ACME 클라이언트 문서를 참조해 캐시된 로컬 구성을 제거하고 새 계정을 설정하되, 필요에 따라 EAB를 지정하세요.

도움 받기 (Get help)

HashiCorp Support에 연락하거나 GitHub 이슈를 만들 때는 조사와 재현을 돕기 위해 다음 정보를 제공해 주세요.

  • ACME 클라이언트 이름과 버전
  • ACME 클라이언트 로그 및/또는 출력
  • Vault 서버 DEBUG 레벨 로그

튜토리얼 (Tutorial)

나만의 인증 기관(CA) 구축하기 가이드를 참고하면 단계별 튜토리얼을 볼 수 있어요.

PKI에 외부 관리 키를 사용하는 방법이 궁금하다면 관리 키를 사용한 PKI 시크릿 엔진도 함께 살펴보세요.

API

PKI 시크릿 엔진은 완전한 HTTP API를 제공해요. 자세한 내용은 PKI 시크릿 엔진 API 문서를 참고해 주세요.

더 알아보기 (Learn more)