자체 서명된 인증서를 사용하여 에이전트 실행

2025-08-15

Azure DevOps Server 2022 | Azure DevOps Server 2020

이 항목에서는 자체 서명된 인증서를 사용하여 자체 호스팅 에이전트를 실행하는 방법을 설명합니다.

SSL 서버 인증서 작업

Enter server URL > https://corp.tfs.com/tfs
Enter authentication type (press enter for Integrated) >
Connecting to server ...
An error occurred while sending the request.

에이전트 진단 로그는 다음을 보여줍니다.

[2017-11-06 20:55:33Z ERR  AgentServer] System.Net.Http.HttpRequestException: An error occurred while sending the request. ---> System.Net.Http.WinHttpException: A security error occurred

이 보안 오류는 Azure Devops Server 호스트 컴퓨터에서 사용한 서버 인증서가 빌드 머신에서 신뢰할 수 없음을 나타낼 수 있습니다. 자체 서명된 ssl 서버 인증서를 OS 인증서 저장소에 설치해야 합니다.

Windows: Windows certificate store
Linux: OpenSSL certificate store
macOS: OpenSSL certificate store for agent version 2.124.0 or below
       Keychain for agent version 2.125.0 or above

몇 가지 명령을 실행하여 인증서가 올바르게 설치되었는지 여부를 쉽게 확인할 수 있습니다. SSL 핸드셰이크가 올바르게 완료되기만 하면 설령 요청에 대해 401을 받더라도 문제가 없을 것입니다.

Windows: PowerShell Invoke-WebRequest -Uri https://corp.tfs.com/tfs -UseDefaultCredentials 
Linux: curl -v https://corp.tfs.com/tfs 
macOS: curl -v https://corp.tfs.com/tfs (agent version 2.124.0 or below, curl needs to be built for OpenSSL)
       curl -v https://corp.tfs.com/tfs (agent version 2.125.0 or above, curl needs to be built for Secure Transport)

권한이 없거나 사용자 지정된 Linux 컴퓨터에 있는 등 다양한 이유로 인해 컴퓨터의 인증서 저장소에 인증서를 성공적으로 설치할 수 없는 경우 에이전트 버전 2.125.0 이상에는 SSL 서버 인증서 유효성 검사 오류를 무시하는 기능이 있습니다.

중요합니다

SSL 서버 인증서 유효성 검사 오류를 무시하는 것은 안전하지 않으며 권장되지 않습니다. 인증서를 머신 인증서 저장소에 설치하는 것이 좋습니다.

에이전트 구성 중 --sslskipcertvalidation 전달

./config.cmd/sh --sslskipcertvalidation

비고

Linux 및 macOS에서 플래그를 사용 --sslskipcertvalidation 하려면 Linux 또는 macOS 컴퓨터의 libcurl 라이브러리를 OpenSSL로 빌드해야 합니다. 추가 정보

SSL 인증서 문제로 Git 원본 가져오기 실패(Windows 에이전트에만 해당)

Windows 에이전트의 일부로 명령줄 Git을 배송합니다. 이 Git 복사본은 모든 Git 관련 작업에 사용합니다. 온-프레미스 Azure DevOps Server 컴퓨터에 대해 자체 서명된 SSL 인증서가 있는 경우 자체 서명된 SSL 인증서를 허용하도록 제공된 Git을 구성해야 합니다. 이 문제를 해결하는 방법에는 두 가지가 있습니다.

에이전트가 사용자 계정으로 실행하여 글로벌 수준에서 다음 git 구성을 설정합니다.
```
git config --global http."https://tfs.com/".sslCAInfo certificate.pem
```
비고

시스템 수준 Git 구성을 설정하는 것은 Windows에서 신뢰할 수 없습니다. 시스템 .gitconfig 파일은 패키지된 Git의 복사본과 함께 저장되며 에이전트가 새 버전으로 업그레이드될 때마다 대체됩니다.
Git가 SChannel을 사용하도록 설정된 2.129.0 이상 버전의 에이전트에서 Pass --gituseschannel을 에이전트 구성 중에 사용하세요.
```
./config.cmd --gituseschannel
```
비고

Git SChannel 에는 자체 서명된 인증서에 대한 제한 요구 사항이 더 많이 있습니다. IIS 또는 PowerShell 명령에서 생성한 자체 서명된 인증서를 사용할 수 없습니다 SChannel.

SSL 클라이언트 인증서 작업

IIS에는 Azure DevOps Server에 들어오는 모든 요청이 일반 자격 증명 외에 클라이언트 인증서를 제공해야 하는 SSL 설정이 있습니다.

IIS SSL 설정을 사용하도록 설정한 경우 Azure DevOps Server에 대해 빌드 머신을 구성하려면 버전 또는 최신 버전을 2.125.0 사용하고 다음 추가 단계를 수행해야 합니다.

필요한 모든 인증서 정보 준비
- CA 인증서 .pem 형식(이 파일에는 CA 인증서의 공개 키와 서명이 포함되어야 합니다. 루트 ca 인증서와 모든 중간 ca 인증서를 하나의 .pem 파일에 넣어야 합니다.)
- 형식의 .pem 클라이언트 인증서(이 파일에는 클라이언트 인증서의 공개 키 및 서명이 포함되어야 합니다.)
- 클라이언트 인증서 프라이빗 키 .pem 형식(이 파일에는 클라이언트 인증서의 프라이빗 키만 포함되어야 합니다.)
- 클라이언트 인증서 보관 패키지 .pfx 형식(이 파일에는 클라이언트 인증서의 서명, 공개 키 및 프라이빗 키가 포함되어야 합니다.)
- SAME 암호를 사용하여 클라이언트 인증서 프라이빗 키와 클라이언트 인증서 보관 패키지를 보호합니다. 둘 다 클라이언트 인증서의 프라이빗 키를 가지고 있기 때문에
머신 인증서 저장소에 CA 인증서 설치
- Linux: OpenSSL 인증서 저장소
- macOS: 시스템 또는 사용자 키체인
- Windows: Windows 인증서 저장소

--sslcacert, --sslclientcert, --sslclientcertkey를 전달하세요. 에이전트 구성 중에 --sslclientcertarchive 및 --sslclientcertpassword.

.\config.cmd/sh --sslcacert ca.pem --sslclientcert clientcert.pem --sslclientcertkey clientcert-key-pass.pem --sslclientcertarchive clientcert-archive.pfx --sslclientcertpassword "mypassword"

클라이언트 인증서 프라이빗 키 암호는 각 플랫폼에 안전하게 저장됩니다.

Linux: Encrypted with a symmetric key based on the machine ID
macOS: macOS Keychain
Windows: Windows Credential Store

루트 인증 기관 트러스트 확인

빌드 에이전트는 Mozilla의 신뢰할 수 있는 루트 인증서에서 파생된 자체 인증서 저장소를 사용하는 Node.js 활용합니다. 보안 통신에 사용되는 루트 인증서는 Node.js 인증 기관 저장소에서 신뢰할 수 있어야 합니다. 이렇게 하면 Azure DevOps Server 컴퓨터에서 인증서를 업데이트한 후 다음 오류를 방지할 수 있습니다.

로컬 발급자 인증서를 가져올 수 없음
SELF_SIGNED_CERT_IN_CHAIN
첫 번째 인증서를 확인할 수 없음

tls.rootCertificates 배열을 사용하여 TLS/SSL 연결을 확인하는 데 사용되는 신뢰할 수 있는 루트 CA(인증 기관)를 확인할 수 있습니다.

# Sample script to extract Node.js root certificates using Node.js.  
node -e ' 
const tls = require("tls"); 
console.log(tls.rootCertificates.join("\n")); 
' > "$ROOT_CERTS_FILE"

Node v7.3.0에 도입된 인증서 NODE_EXTRA_CA_CERTS 환경 변수를 신뢰하도록 Node.js 구성하려면 기본 번들 외에도 Node에서 신뢰하는 하나 이상의 추가 CA 인증서가 포함된 파일을 지정할 수 있습니다. NODE_EXTRA_CA_CERTS 트러스트 저장소에 추가됩니다.

인증서를 PEM 형식으로 내보내기: 서버 또는 CA에서 루트(및 필요한 경우 중간) 인증서를 PEM 인코딩 파일로 내보냅니다. 이 형식은 -----BEGIN 인증서----- 및 base64 데이터가 있는 텍스트 파일입니다. DER가 아닌 Base-64로 인코딩된 PEM인지 확인합니다. (Windows, . CER 파일은 둘 중 하나일 수 있습니다. 혼동을 피하기 위해 .pem으로 이름을 바꿀 수 있습니다. 파일에는 실제로 확장명이 있을 수 있지만 .pem 또는 .crt는 표준입니다.) 여러 개의 내부 CA(체인)가 있는 경우 하나의 파일에 연결할 수 있습니다. 노드는 해당 파일의 모든 인증서를 읽습니다.
알려진 경로(예: C:\certs\CorpRootCA.pem 또는 /etc/ssl/certs/CorpRootCA.pem)에 배치하여 빌드 에이전트에서 PEM을 사용할 수 있도록 합니다.
해당 PEM 파일을 가리키는 OS 환경 변수 NODE_EXTRA_CA_CERTS 설정합니다. 예를 들어 Windows에서는 PowerShell을 사용할 수 있습니다.

[Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:\certs\CorpRootCA.pem", "Machine")

에이전트 클라이언트 인증서 지원에 대해 자세히 알아봅니다.