Announcing Public Preview of the Root Cert API in App Service Environment v3

What is the Root Cert API?

The Root Cert API allows customers to programmatically add root certificates to their ASE, making them available during the startup of apps.

Root certificates are public certificates that identify a root certificate authority (CA). These are essential for establishing trust in secure communications. By adding root certificates to your ASE, all web apps hosted within that ASE will have them installed in their root store. This ensures that apps can securely communicate with internal services or APIs that use certificates issued by private or enterprise CAs.

Previously, this functionality was only available in private preview through a workaround involving certificate uploads and a special app setting and included a number of limitations.

With the new Root Cert API, we’re making this capability official, streamlined, and cross-platform—including full support for both Windows and Linux-based apps.

Why This Matters

This feature is important for enterprise customers and developers who rely on secure, internal communication between services. By integrating root certs directly into the ASE startup process, you can:

• Ensure consistent trust settings across all apps in the ASE
• Eliminate the need for per-app configurations
• Simplify certificate lifecycle management
• Improve security posture by reducing manual steps and potential misconfigurations

How It Works

The Root Cert API provides a clean, RESTful interface to manage root certificates. Once added, these certificates are automatically injected into the trust store of apps running in the ASE at startup—no additional configuration required. At this time, the feature is not available in the Azure Portal, but can be used with the Azure CLI, ARM/Bicep, and REST API.

Important Considerations

• A cert can be added to an ASE using API/CLI/Terraform.
• If you've added a cert to an ASE with existing/running apps, you must STOP and then START each of your apps so that that their certificate store gets updated with the new root cert. Adding all certs before creating your apps is recommended as it eliminates the need to stop and then start all apps individually.
  • STOP/START is not the same as Restarting your app. You must use the dedicated STOP/START commands. This can be done in the portal, with the Azure CLI, or with the APIs directly.
  • If you have a lot of apps and want to script this process, that can be done using the CLI or APIs.
  • Starting and stopping your apps will cause temporary outages while the apps are stopped.

  • Portal ("Start" will appear in the same location once the app is stopped)

    
  • API
    • Web Apps - Stop - REST API (Azure App Service) | Microsoft Learn
    • Web Apps - Start - REST API (Azure App Service) | Microsoft Learn
  • CLI
    • az webapp stop | Microsoft Learn
    • az webapp start | Microsoft Learn
• During the public preview, you must provide the entire certificate blob in the create command to add the certificate. You can't upload a .cer file at this time.

Add a Root Cert

For both methods, you must provide the body with the PUT request. Replace the placeholders for subscription ID, resource group, and ASE name. And give you cert a name. The "blob" is the raw certificate blob from your root cert. Don't forget to STOP and then START your apps after the cert is added if you added the cert to an ASE with existing apps.

API

PUT subscriptions/<subscription>/resourceGroups/<resourceGroup>/providers/Microsoft.Web/hostingEnvironments/<AseName>/publicCertificates/<certName>?api-version=2024-04-01

Body: { "location": <location>, "properties": { "blob": <raw certificate blob>, "isRoot": true } }

CLI

az rest --method put \
--url https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Web/hostingEnvironments/{aseName}/publicCertificates/{certName}?api-version=2024-04-01 \
--body "{'location': '<locationName>', 'properties': {'blob': '<raw certificate blob>', 'isRoot': 'true'}}"

Terraform

Note that with terraform, you must include "schema_validation_enabled = false". This is a limitation for public preview that we will be looking to remove once we make this feature generally available.

resource "azapi_resource" "<cert_name>" {
  type = "Microsoft.Web/hostingEnvironments/publicCertificates@2023-12-01"
  name = "<cert_name>"
  parent_id = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Web/hostingEnvironments/<aseName>"
  body = jsonencode({
    properties = {
      blob = "<blob>"
      isRoot = true
    }
    kind = "string"
  })
  schema_validation_enabled = false
}

ARM

Resource format

To create a Microsoft.Web/hostingEnvironments/publicCertificates resource, add the following JSON to your template. 

{
    "type": "Microsoft.Web/hostingEnvironments/publicCertificates", 
    "apiVersion": "2024-11-01", 
    "name": "string", 
    "properties": {
        "blob": "<blob>", 
        "isRoot": "bool" 
    } 
}

Property values 

PublicCertificateProperties 

Remove a Root Cert

API

DELETE subscriptions/<subscription>/resourceGroups/<resourceGroup>/providers/Microsoft.Web/hostingEnvironments/<AseName>/publicCertificates/<certName>?api-version=2024-04-01

CLI

az rest --method delete \
--url https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Web/hostingEnvironments/{aseName}/publicCertificates/{certName}?api-version=2024-04-01

Check Root Cert

Fetch certificate by name:

API

GET subscriptions/<subscription>/resourceGroups/<resourceGroup>/providers/Microsoft.Web/hostingEnvironments/<AseName>/publicCertificates/<certName>?api-version=2024-04-01

CLI

az rest --method get \
--url https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Web/hostingEnvironments/{aseName}/publicCertificates/{certName}?api-version=2024-04-01

Fetch all public certificates in the ASE:

API

GET subscriptions/<subscription>/resourceGroups/<resourceGroup>/providers/Microsoft.Web/hostingEnvironments/<AseName>/publicCertificates?api-version=2024-04-01

CLI

az rest --method get \
--url https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Web/hostingEnvironments/{aseName}/publicCertificates?api-version=2024-04-01

What’s Next

We’re eager to hear your feedback during the public preview. Your input will help us refine the experience and ensure it meets your needs before general availability.

If you’ve been waiting for a better way to manage root certs in ASE, now’s the time to try it out.