How to Publish an Authenticated Azure App Service Through Application Gateway Without Breaking Health Probes

A common web service design pattern is placing an Azure App Service behind an Azure Application Gateway so the application can be published through a central ingress point with consistent routing, inspection, and access controls. The design works well until the moment App Service Authentication is enabled and the backend suddenly starts showing as unhealthy.

Application Gateway health probes are just HTTP requests and if the probe is sent to a path that now requires authentication, the backend stops returning a healthy response and the gateway will begin displaying 502 Bad Gateway errors when attempting to browse the site.

I wanted to create a small environment that replicates the scenario so I can demonstrate how to correctly fix this issue. What I ended up creating this GitHub repo: https://github.com/terenceluk/appgw-appservice-auth-bypass-health-check-demo where I have Terraform deploy an Application Gateway, an App Service, and file-based App Service Authentication that excludes a dedicated health endpoint from the authentication requirement.

In this scenario, the Application Gateway probe is not a signed-in user. It is simply testing whether the backend is reachable and healthy. If the probe lands on / and / now redirects to Microsoft Entra ID, the gateway no longer receives the healthy 200 response and instead receives a 401 response:

Received invalid status code: 401 in the backend server’s HTTP response. As per the health probe configuration, 200-399 is the acceptable status code. Either modify probe configuration or resolve backend issues. 

The result is that the backend will be marked unhealthy even though the application is functioning exactly as designed.

1. Deploy an Azure Application Gateway that publishes an Azure App Service.
2. Turn on App Service Authentication with Microsoft Entra ID.
3. Use file-based authentication configuration so I can explicitly exclude a health endpoint.
4. Point the Application Gateway custom probe to that excluded endpoint.

The excluded path becomes the bridge between security and availability. Users still have to authenticate to access the application, while the gateway retains a path that can answer anonymously with a simple 200 OK.

{
  "platform": {
    "enabled": true,
    "configFilePath": "/home/auth.json"
  }
}

1. infra/ contains the Terraform configuration.
2. src/web/ contains a tiny Node.js site that serves the welcome page and the health endpoint.

The Terraform code deploys the following components:

1. A resource group.
2. A virtual network and dedicated Application Gateway subnet.
3. A Standard_v2 Application Gateway with a public frontend.
4. A Linux App Service Plan.
5. A Linux Web App deployed by ZIP package.
6. A Microsoft Entra application registration and client secret for App Service Authentication.
7. An authsettingsV2 configuration applied through the AzAPI provider.

The site serves:

1. / as a simple welcome page.
2. /healthz as a JSON endpoint that always returns 200 OK.

The startup script reads environment variables and writes /home/auth.json from an auth.template.json file before the app begins listening for requests.

This is the key part of the startup logic:

const templatePath = path.join(__dirname, "auth.template.json");
const outputPath = "/home/auth.json";

"globalValidation": {
  "requireAuthentication": true,
  "unauthenticatedClientAction": "RedirectToLoginPage",
  "redirectToProvider": "azureactivedirectory",
  "excludedPaths": [
    "/healthz"
  ]
}

resource "azapi_resource" "authsettings_v2" {
  type      = "Microsoft.Web/sites/config@2022-09-01"
  name      = "authsettingsV2"
  parent_id = azurerm_linux_web_app.main.id

  body = {
    properties = {
      platform = {
        enabled        = true
        configFilePath = "/home/auth.json"
      }
    }
  }
}

Packaging — data "archive_file"

When terraform apply runs, before any Azure API calls are made, Terraform executes the archive_file data source:

data "archive_file" "web_package" {
  type        = "zip"
  source_dir  = "${path.module}/../src/web"
  output_path = "${path.module}/build/webapp.zip"
}

Uploading — zip_deploy_file

The azurerm_linux_web_app resource has a zip_deploy_file argument that points to the output of the archive:

zip_deploy_file = data.archive_file.web_package.output_path

The app setting SCM_DO_BUILD_DURING_DEPLOYMENT = "false" is also set so that Kudu skips attempting to run npm install after extraction. Because the app uses only built-in Node.js modules, this saves deployment time and avoids needing network access to npm from the App Service.

Startup sequence — app_command_line

The App Service site_config specifies a custom startup command:

app_command_line = "node startup.js && node server.js"

const replacements = {
  "__AAD_CLIENT_ID__":             process.env.AUTH_AAD_CLIENT_ID,
  "__ALLOWED_AUDIENCE__":          process.env.AUTH_ALLOWED_AUDIENCE,
  "__OPENID_ISSUER__":             process.env.AUTH_OPENID_ISSUER,
  "__CLIENT_SECRET_SETTING_NAME__":"AAD_CLIENT_SECRET",
  "__HEALTH_PATH__":               process.env.HEALTH_PATH
};

Environment variables

All values the startup and server scripts need are injected as App Service app settings controlled by Terraform:

Because these values are managed by Terraform, changing any of them and running terraform apply will update the App Service app setting and trigger a restart automatically.

This is the important part of the probe definition:

probe {
  name                                      = "healthz-probe"
  protocol                                  = "Https"
  path                                      = "/healthz"
  pick_host_name_from_backend_http_settings = true

  match {
    status_code = ["200-399"]
  }
}

1. The path points to the endpoint excluded from authentication.
2. The probe uses the backend host name expected by the App Service.

Without the correct host name, App Service can fail the request for an entirely different reason. Without the excluded path, the probe will be challenged by authentication.

The easiest sequence is:

1. Deploy the sample as written and confirm the Application Gateway backend is healthy.
2. Browse to the gateway root and verify that the request is redirected to Microsoft Entra sign-in.
3. Browse to /healthz and verify that the endpoint returns 200 OK anonymously.
4. Simulate a probe failure by changing HEALTH_STATUS_CODE to a non-2xx value. If you change it through Terraform, run terraform apply. If you change it directly in App Service settings, save the change and restart the app. The backend will be marked unhealthy even though authentication is not involved.
5. Restore the status code to 200 to bring the backend back to healthy.

That gives you a clean before-and-after demonstration of both the authentication exclusion and the status code effect on probe health.

If you want Terraform to remain the source of truth for the setting, update health_status_code in terraform.tfvars to 503, then run:

terraform apply -var-file="terraform.tfvars"

{
  "status": "Unhealthy",
  "statusCode": 503,
  "timestampUtc": "2026-04-23T12:00:00.000Z"
}

To restore it, set health_status_code back to 200 in terraform.tfvars and run:

terraform apply -var-file="terraform.tfvars"

The cleanest way to do this is through Azure Resource Explorer, which gives direct access to the Azure Resource Manager API for any resource in your subscription.

Step 6.1: Open Azure Resource Explorer

Navigate to https://resources.azure.com and sign in with your Azure credentials.

Step 6.2: Find Your Web App’s Authentication Configuration

Expand the tree on the left in this order:

1. subscriptions → your subscription name
2. resourceGroups → your resource group (it will start with terence-demo-)
3. providers → Microsoft.Web
4. sites → your web app name
5. config → authsettingsV2

Step 6.3: Switch to Read/Write Mode

At the top of the page, click Read/Write. This enables editing through the REST API. Without this step the interface is read-only.

Step 6.4: Review the Current Configuration

You will see a JSON view of the authsettingsV2 resource. The important part of the response will be inside properties.platform:

{
  "properties": {
    "platform": {
      "enabled": true,
      "configFilePath": "/home/auth.json"
    }
  }
}

Step 6.5: Edit the Configuration

Click Edit at the top of the JSON view. You can modify the properties block to add, change, or extend the platform configuration. For example, to reference a different configuration file:

{
  "properties": {
    "platform": {
      "enabled": true,
      "configFilePath": "/home/auth.json"
    }
  }
}

{
  "properties": {
    "platform": {
      "enabled": true,
      "configFilePath": null
    }
  }
}

Click PUT at the top of the editor to submit the change through the REST API. The update takes effect within a few seconds and does not require an App Service restart.

Note: Changes made in Azure Resource Explorer will be overwritten the next time you run terraform apply, because Terraform owns the authsettingsV2 resource. Use Resource Explorer for inspection and temporary changes; keep Terraform as the source of truth for persistent configuration.

The key parameters to review are:

The deployment also requires permissions to create Azure resources and register applications in Microsoft Entra ID.

The App Service in this sample is locked down behind a private endpoint, which also makes the Kudu SCM endpoint private. If app_service_public_network_access_enabled is false during the first apply, Terraform cannot reach Kudu and the deploy will fail.

The recommended sequence is:

Step 1 — Initial deploy with public access enabled

Set app_service_public_network_access_enabled = true in terraform.tfvars, then run:

terraform init
terraform plan -var-file="terraform.tfvars"
terraform apply -var-file="terraform.tfvars"

Step 2 — Lock down public access

Once the deployment is confirmed working, change app_service_public_network_access_enabled to false in terraform.tfvars and run:

terraform apply -var-file="terraform.tfvars"

Re-deploying after lockdown. If you later modify src/web/ files and run terraform apply, the ZIP upload through Kudu will fail because Kudu is now private. Temporarily set app_service_public_network_access_enabled = true, apply, then set it back to false and apply again.

After deployment, capture the following for the blog post if you want to include screenshots:

1. The Application Gateway backend health page showing the backend as healthy.
2. The App Service Authentication configuration reference through authsettingsV2.
3. A browser session showing authentication for /.
4. A browser or curl session showing a successful anonymous response from /healthz.

File-based App Service Authentication configuration provides a clean way to solve the problem because it lets us preserve strong authentication for the application while carving out a very narrow anonymous path for platform health checks.

If you need to publish an authenticated App Service through Application Gateway, this is the pattern I would start with.

• Configure App Service Authentication using a file (Microsoft Learn)
• Microsoft.Web sites/config authsettingsV2 — Terraform reference (Microsoft Learn)