Run the agent with a self-signed certificate
Azure DevOps Server 2022 - Azure DevOps Server 2019 | TFS 2018
This topic explains how to run a self-hosted agent with a self-signed certificate.
This article applies to agent versions 2.x and newer.
Work with SSL server certificate
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.
Agent diagnostic log shows:
[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
This error may indicate the server certificate you used on your TFS server is not trusted by the build machine. Make sure you install your self-signed ssl server certificate into the OS certificate store.
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
You can easily verify whether the certificate has been installed correctly by running few commands. You should be good as long as SSL handshake finished correctly even you get a 401 for the request.
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)
If somehow you can't successfully install certificate into your machine's certificate store due to various reasons, like: you don't have permission or you are on a customized Linux machine. The agent version 2.125.0 or above has the ability to ignore SSL server certificate validation error.
This is not secure and not recommended, we highly suggest you to install the certificate into your machine certificate store.
--sslskipcertvalidation during agent configuration
There is limitation of using this flag on Linux and macOS
The libcurl library on your Linux or macOS machine needs to built with OpenSSL, More Detail
Git get sources fails with SSL certificate problem (Windows agent only)
We ship command-line Git as part of the Windows agent. We use this copy of Git for all Git related operation. When you have a self-signed SSL certificate for your on-premises TFS server, make sure to configure the Git we shipped to allow that self-signed SSL certificate. There are 2 approaches to solve the problem.
Set the following git config in global level by the agent's run as user.
git config --global http."https://tfs.com/".sslCAInfo certificate.pem
Setting system level Git config is not reliable on Windows. The system .gitconfig file is stored with the copy of Git we packaged, which will get replaced whenever the agent is upgraded to a new version.
Enable git to use
SChannelduring configure with 2.129.0 or higher version agent Pass
--gituseschannelduring agent configuration
Git SChannel has more restrict requirement for your self-signed certificate. Self-singed certificate that generated by IIS or PowerShell command may not be capable with SChannel.
Work with SSL client certificate
IIS has an SSL setting that requires all incoming requests to Azure DevOps Server or TFS must present client certificate in addition to the regular credential.
When that IIS SSL setting enabled, you need to use
2.125.0 or above version agent and follow these extra steps in order to configure the build machine against your Azure DevOps or TFS server.
Prepare all required certificate information
- CA certificate(s) in
.pemformat (This should contain the public key and signature of the CA certificate, you need put the root ca certificate and all your intermediate ca certificates into one
- Client certificate in
.pemformat (This should contain the public key and signature of the Client certificate)
- Client certificate private key in
.pemformat (This should contain only the private key of the Client certificate)
- Client certificate archive package in
.pfxformat (This should contain the signature, public key and private key of the Client certificate)
SAMEpassword to protect Client certificate private key and Client certificate archive package, since they both have client certificate's private key
- CA certificate(s) in
Install CA certificate(s) into machine certificate store
- Linux: OpenSSL certificate store
- macOS: System or User Keychain
- Windows: Windows certificate store
--sslclientcertpasswordduring agent configuration.
.\config.cmd/sh --sslcacert ca.pem --sslclientcert clientcert.pem --sslclientcertkey clientcert-key-pass.pem --sslclientcertarchive clientcert-archive.pfx --sslclientcertpassword "mypassword"
Your client certificate private key password is securely stored on each platform.
Linux: Encrypted with a symmetric key based on the machine ID macOS: macOS Keychain Windows: Windows Credential Store
Learn more about agent client certificate support.