Solving "Self-Signed Certificate in Certificate Chain" Error in Azure DevOps Self-Hosted Agents

When managing self-hosted agents in Azure DevOps, one of the more common problems DevOps engineers encounter is the "self signed certificate in certificate chain" error. This error typically arises when your DevOps pipeline is unable to validate the SSL certificate provided by a server. In most cases, this happens because the certificate is self-signed or issued by a certificate authority (CA) that isn’t trusted by the agent.

In this blog post, I’ll walk you through how I faced this issue, the different methods I tried to resolve it, and ultimately how I managed to secure the connection between my pipeline and server.

---

The Problem: "Self Signed Certificate in Certificate Chain" Error

The error itself usually looks like this:

Error: self signed certificate in certificate chain
    at TLSSocket.onConnectSecure (node:_tls_wrap:1532:34)
    at TLSSocket.emit (node:events:527:28)
    at TLSSocket._finishInit (node:_tls_wrap:946:8)
    at TLSWrap.ssl.onhandshakedone (node:_tls_wrap:727:12)

This error is encountered when using a self-signed certificate on the server hosting Azure DevOps or on the services being deployed through Azure DevOps. Essentially, the agent does not trust the certificate being presented, causing the connection to fail.

---

Two Ways to Resolve This Issue

1. Disable SSL Certificate Verification (Quick but Less Secure)

One way to bypass the problem is by disabling SSL certificate validation. While this approach works and is quick to implement, it’s not ideal for production environments since it compromises security. Still, for non-production environments or quick testing, it may be a useful workaround.

Solution 1: Set NODE_TLS_REJECT_UNAUTHORIZED in Pipeline

If you're running the pipeline using Azure DevOps classic pipelines (UI-based), you can add an environment variable in your release pipeline to bypass the SSL validation. Here’s how you can do it.

In the Classic Pipeline UI:

1. Go to your release pipeline and click on Edit.

2. Click on the specific task that is failing.

3. Select the Variables tab.

4. Add a new variable:

   • Name: NODE_TLS_REJECT_UNAUTHORIZED

   • Value: 0

   • Leave the checkbox for secret unchecked.

5. Save the pipeline and redeploy.

By setting this variable, you instruct Node.js (used by Azure DevOps agents) to ignore SSL certificate validation.

Solution 2: Set NODE_TLS_REJECT_UNAUTHORIZED on the Server (Self-Hosted Agent)

For a more permanent and system-wide solution, you can set the environment variable on the self-hosted agent itself. This will make sure that SSL validation is bypassed for all connections from that agent.

On Windows:

1. Open Command Prompt or PowerShell as an administrator.

2. Set the environment variable:

    set NODE_TLS_REJECT_UNAUTHORIZED=0
   

   Alternatively, you can add this to the system environment variables:

   • Right-click on This PC > Properties > Advanced system settings > Environment Variables.

   • Create a new System Variable:

     • Name: NODE_TLS_REJECT_UNAUTHORIZED

     • Value: 0

3. Restart the Azure DevOps Agent service:

   • Open Services, find the agent service (often named something like VSTS Agent), and restart it.

On Linux:

1. Open a terminal window.

2. Set the environment variable temporarily by running:

    export NODE_TLS_REJECT_UNAUTHORIZED=0
   

3. To make this permanent, add the line to your shell profile file (e.g., ~/.bashrc, ~/.bash_profile, or /etc/environment).

4. Restart the agent service:

    sudo systemctl restart your-agent-service-name
   

This will globally disable SSL validation for all tasks run by this agent.

---

2. Install the Self-Signed SSL Certificate (More Secure)

Rather than disabling SSL checks, a more secure approach is to install the self-signed certificate on the self-hosted agent. This allows the agent to trust the certificate without compromising security.

Installing the SSL Certificate on Windows Agents:

1. Obtain the self-signed certificate (.crt or .cer format) from the DevOps server administrator.

2. Double-click the certificate file and select Install Certificate.

3. When prompted, choose Local Machine and click Next.

4. Select Place all certificates in the following store, then click Browse.

5. Choose Trusted Root Certification Authorities and click OK.

6. Complete the installation process by clicking Next and Finish.

7. Restart the Azure DevOps Agent service:

   • Open Services, find the agent service, and restart it.

Installing the SSL Certificate on Linux Agents:

1. Obtain the self-signed certificate (.crt file).

2. Copy the certificate to the system’s trusted certificates directory:

    sudo cp your_certificate.crt /usr/local/share/ca-certificates/
   

3. Update the trusted certificates store:

    sudo update-ca-certificates
   

4. Restart the agent service:

    sudo systemctl restart your-agent-service-name
   

By installing the certificate, you are telling the system that the certificate is trustworthy, and it will be accepted in future connections.

Remove-Item Env:NODE_TLS_REJECT_UNAUTHORIZED

---

Conclusion

When faced with the "self signed certificate in certificate chain" issue, you have two main options:

• Bypass SSL certificate validation using the NODE_TLS_REJECT_UNAUTHORIZED environment variable.

• Install the self-signed SSL certificate on your agent to ensure trusted and secure communication.

While disabling SSL verification is quick and easy, I highly recommend installing the certificate for a more secure and long-term solution, especially in production environments.

By following the steps outlined above, you can ensure smooth pipeline executions in Azure DevOps without compromising security.

$env:NODE_TLS_REJECT_UNAUTHORIZED="0"

echo $env:NODE_TLS_REJECT_UNAUTHORIZED

---

Feel free to tailor this blog to match your writing style or add more details from your experience!