Skip to content

Oryx build using certificates #524

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tulikac merged 7 commits into from
Sep 10, 2025
Merged

Oryx build using certificates #524

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2f53ec5
GHA for sidecars
tulikac Sep 8, 2025
dafa4de
Use certificates with Oryx build
tulikac Sep 8, 2025
e652cbd
cleaning up
tulikac Sep 8, 2025
31a841b
updated the grep command
tulikac Sep 8, 2025
cc09af2
changes suggested by Byron
tulikac Sep 9, 2025
656bd1d
some more fixes
tulikac Sep 9, 2025
6e6b716
changed the title to make it shorter
tulikac Sep 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions _posts/2025-09-08-Oryx-build-certificate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
title: "App Service builds behind proxies: fixing trust with a public certificate"
author_name: "Tulika Chaudharie"
toc: true
toc_sticky: true
---

**TL;DR**: If your organization uses a TLS-inspecting proxy (e.g., Zscaler), some of the traffic originating from App Service build infrastructure may be re-signed by the proxy. App Service doesn’t trust that proxy cert by default, so the build fails.
Set the app setting **`WEBSITE_INSTALL_PUBLIC_CERTS_IN_KUDU=true`** and upload the proxy’s public certificate (.cer). App Service will install the certificate and your builds will succeed.

---

## Why this happens

During build, App Service downloads build assets from the its build CDN over HTTPS. When a corporate proxy intercepts and re-signs TLS, App Service sees a certificate chain it doesn’t recognize and refuses the connection, causing the build to fail.

## What’s new

A new app setting, **`WEBSITE_INSTALL_PUBLIC_CERTS_IN_KUDU`**, tells App Service to install any **public key certificates (.cer)** you upload into its trust store used for the build.

---

## Step-by-step

### 1) Upload the proxy’s public certificate

In the portal, navigate to your Web App ➜ **Certificates** ➜ **Public key certificates (.cer)** ➜ **Add certificate**.
Upload the organization’s TLS inspection CA (root or intermediate) **public** certificate.

![Add Certificate]({{site.baseurl}}/media/2025/09/add-cert.jpg)

> Tip: This is a public certificate only—no private key and no password.

### 2) Turn on the app setting

Portal: **Configuration** ➜ **Application settings** ➜ add (Or **Settings** ➜ **Environment Variables** ➜ **App Settings** ➜ Add)
`WEBSITE_INSTALL_PUBLIC_CERTS_IN_KUDU = true` ➜ **Save**. This will automatically restart the app.

CLI (equivalent):

```bash
az webapp config appsettings set \
-g <resource-group> -n <app-name> \
--settings WEBSITE_INSTALL_PUBLIC_CERTS_IN_KUDU=true
```

### 3) Verify the certificate is installed

Open **Advanced Tools (Kudu)** ➜ **Bash** and check:

```bash
ls -l /etc/ssl/certs
# (optional) find the installed cert by name or subject
grep -l "<certificate-name>" /etc/ssl/certs/*.crt

# compare thumbprint
openssl x509 -in /etc/ssl/certs/<your-cert>.crt -noout -fingerprint -sha1
```

Compare the fingerprint with the thumbprint shown for your uploaded cert in the **Certificates** blade.

### 4) Trigger a build

Deploy again (Deployment Center, GitHub Actions, az webapp deployment, etc.).
When the proxy presents its certificate, App Service now trusts it and the application build completes.

---

## Troubleshooting

* **Still seeing x509/certificate unknown errors?**
Ensure you uploaded the exact CA that signs your proxy’s certs (often an org-specific intermediate), in **.cer** (DER/BASE64) form.

* **Multiple proxies / chains**
If your environment uses a chain, upload all relevant public CA certs.

* **Scope**
This affects App Service build infrastructure's outbound trust for the app. It does not grant trust to private keys or change TLS for your site’s inbound traffic.

---

## Summary

By uploading your organization’s proxy CA **public** certificate and enabling **`WEBSITE_INSTALL_PUBLIC_CERTS_IN_KUDU`**, App Service for Linux installs the certificate into its trust store. App Service can then fetch dependencies through Zscaler (or similar proxies) and your builds proceed normally—no more failed builds due to untrusted certificates.
Binary file added media/2025/09/add-cert.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.