add early draft for consolidated article AppGw and App Svc aligned to hostname best practices

Author: xstof

articles/application-gateway/configuration-http-settings.md

@@ -5,7 +5,7 @@ services: application-gateway
 author: vhorne
 ms.service: application-gateway
 ms.topic: conceptual
-ms.date: 09/09/2020
+ms.date: 02/17/2022
 ms.author: surmb
 ---
 
@@ -73,9 +73,6 @@ This setting lets you configure an optional custom forwarding path to use when t
   | /pathrule/home/secondhome/ | /pathrule/home* | /override/            | /override/secondhome/        |
   | /pathrule/                 | /pathrule/      | /override/            | /override/                   |
 
-## Use for app service
-
-This is a UI only shortcut that selects the two required settings for the Azure App Service back end. It enables **pick host name from back-end address**, and it creates a new custom probe if you don't have one already. (For more information, see the [Pick host name from back-end address](#pick-host-name-from-back-end-address) setting section of this article.) A new probe is created, and the probe header is picked from the back-end member's address.
 
 ## Use custom probe
 
@@ -84,6 +81,18 @@ This setting associates a [custom probe](application-gateway-probe-overview.md#c
 > [!NOTE]
 > The custom probe doesn't monitor the health of the back-end pool unless the corresponding HTTP setting is explicitly associated with a listener.
 
+## Configuring the host name
+
+Application Gateway allows for the connection to the backend to be established using a *different* hostname than the one used by the client to connect to Application Gateway.  Changing the hostname used towards the backend into a value that is different from the hostname that is used to connect to Application Gateway should however be done with care.  
+
+In a typical production-grade configuration, one will typically want to keep the host name used by the client towards Application Gateway the same as the hostname as used by Application Gateway towards the backend.  This avoid potential issues with absolute URLs, redirect URLs and host-bound cookies.
+
+Before setting up Application Gateway that deviates from this, please review the implications of such configuration as discussed in more detail in Architecture Center: [Preserve the original HTTP host name between a reverse proxy and its backend web application](/azure/architecture/best-practices/host-name-preservation)
+
+There are two aspects of an HTTP setting that influence the [`Host`](https://datatracker.ietf.org/doc/html/rfc2616#section-14.23) HTTP header that is used by Application Gateway to connect to the backend:
+- "Pick host name from backend-address"
+- "Host name override"
+
 ## Pick host name from back-end address
 
 This capability dynamically sets the *host* header in the request to the host name of the back-end pool. It uses an IP address or FQDN.
@@ -92,9 +101,9 @@ This feature helps when the domain name of the back end is different from the DN
 
 An example case is multi-tenant services as the back end. An app service is a multi-tenant service that uses a shared space with a single IP address. So, an app service can only be accessed through the hostnames that are configured in the custom domain settings.
 
-By default, the custom domain name is *example.azurewebsites.net*. To access your app service by using an application gateway through a hostname that's not explicitly registered in the app service or through the application gateway's FQDN, you override the hostname in the original request to the app service's hostname. To do this, enable the **pick host name from backend address** setting.
+By default, the custom domain name is *example.azurewebsites.net*. To access your app service by using an application gateway through a hostname that's not explicitly registered in the app service or through the application gateway's FQDN, you can override the hostname in the original request to the app service's hostname. To do this, enable the **pick host name from backend address** setting.
 
-For a custom domain whose existing custom DNS name is mapped to the app service, you don't have to enable this setting.
+For a custom domain whose existing custom DNS name is mapped to the app service, you don't have to enable this setting.  As described earlier, this is usually the preferred way of working.
 
 > [!NOTE]
 > This setting is not required for App Service Environment, which is a dedicated deployment.

articles/application-gateway/configure-web-app.md

@@ -0,0 +1,124 @@
+---
+title: Manage traffic to App Service
+titleSuffix: Azure Application Gateway
+description: This article provides guidance on how to configure Azure App service web apps as members in backend pool on an existing or new Application Gateway.
+services: application-gateway
+author: xstof
+ms.service: application-gateway
+ms.topic: how-to
+ms.date: 17/02/2022
+ms.author: christoc
+---
+<!-- https://docs.microsoft.com/en-us/azure/application-gateway/configure-web-app-portal -->
+
+# Configure App Service with Application Gateway
+
+Application gateway allows you to have an App Service app or other multi-tenant service as a back-end pool member. In this article, you learn to configure an App Service app with Application Gateway.  The configuration for Application Gateway will differ depending on how App Service will be accessed.
+
+The first option is to have Application Gateway access App Service using it's default domain, suffixed as ".azurewebsites.net".  This is the easiest configuration as it does not require a custom domain.  As such it allows for a quick convenient setup.  Note however that this configuration comes with limitations and that we recommend to review the implications of using different host names between the client and Application Gateway and between Application and App Service in the backend.  For more information, please review the article in Architecture Center: [Preserve the original HTTP host name between a reverse proxy and its backend web application](/azure/architecture/best-practices/host-name-preservation)
+
+The second option makes use of a custom domain on both Application Gateway and the App Service in the backend.  This the configuration which is commonly recommended for production-grade scenarios and meets the practice of not changing the host name in the request flow.  It does require however you have a custom domain (and associated certificate) available so to avoid having to rely on the default ".azurewebsites" domain.
+
+
+<!-- see example: https://github.dev/MicrosoftDocs/azure-docs/blob/main/articles/app-service/quickstart-dotnetcore.md -->
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="app-service-domainconfig-defaultdomain"
+<!-- markdownlint-enable MD044 -->
+
+When App Service does not have a custom domain associated with it, the host header on the incoming request on the web application will need to be set to the default domain, suffixed with ".azurewebsites.net" or else the platform will not be able to properly route the request.
+
+This means that the host header in the original request received by the Application Gateway will be different from the host name of the backend App Service.
+
+:::zone-end
+
+:::zone target="docs" pivot="app-service-domainconfig-customdomain"
+
+By associating both Application Gateway and App Service in the backend pool to the same domain name, the request flow does not need to override host name and the backend web application will see the original host as was used by the client.
+
+:::zone-end
+
+In this article you'll learn how to:
+- Add App Service as backend pool to the Application Gateway
+- Configure the HTTP Settings for the connection to App Service
+
+## Prerequisites
+
+:::zone target="docs" pivot="app-service-domainconfig-defaultdomain"
+
+- Application gateway: Create an application gateway without a backend pool target. For more information, see [Quickstart: Direct web traffic with Azure Application Gateway - Azure portal](quick-create-portal.md)
+
+- App service: If you don't have an existing App service, see [App service documentation](../app-service/index.yml).
+
+:::zone-end
+
+:::zone target="docs" pivot="app-service-domainconfig-customdomain"
+
+- Application Gateway: Create an application gateway without a backend pool target. For more information, see [Quickstart: Direct web traffic with Azure Application Gateway - Azure portal](quick-create-portal.md)
+
+- App Service: If you don't have an existing App service, see [App service documentation](../app-service/index.yml).
+
+- A custom domain name and associated certificate, stored in Key Vault.  For more information on how to store certificates in Key Vault, see [Tutorial: Import a certificate in Azure Key Vault](../key-vault/certificates/tutorial-import-certificate.md)
+
+:::zone-end
+
+## Add App service as backend pool
+
+### [Azure Portal](#tab/azp)
+
+1. In the Azure portal, select your application gateway.
+
+2. Under **Backend pools**, select the backend pool.
+
+3. Under **Target type**, select **App Services**.
+
+4. Under **Target** select your App Service.
+
+   :::image type="content" source="./media/configure-web-app-portal/backend-pool.png" alt-text="App service backend":::
+   
+   > [!NOTE]
+   > The dropdown only populates those app services which are in the same subscription as your Application Gateway. If you want to use an app service which is in a different subscription than the one in which the Application Gateway is, then instead of choosing **App Services** in the **Targets** dropdown, choose **IP address or hostname** option and enter the hostname (example.azurewebsites.net) of the app service.
+
+5. Select **Save**.
+
+:::zone target="docs" pivot="app-service-domainconfig-customdomain"
+
+TEST - custom text for custom domain
+
+:::zone-end
+
+:::zone target="docs" pivot="app-service-domainconfig-defaultdomain"
+
+TEST - custom text for default domain
+
+:::zone-end
+
+### [Powershell](#tab/powershell)
+
+TODO
+
+
+## Edit HTTP settings for App Service
+
+1. Under **HTTP Settings**, select the existing HTTP setting.
+
+2. Under **Override with new host name**, select **Yes**.
+3. Under **Host name override**, select **Pick host name from backend target**.
+4. Select **Save**.
+
+   :::image type="content" source="./media/configure-web-app-portal/http-settings.png" alt-text="Pick host name from backend http settings":::
+
+## Additional configuration in case of redirection to app service's relative path
+
+When the app service sends a redirection response to the client to redirect to its relative path (For example, a redirect from `contoso.azurewebsites.net/path1` to `contoso.azurewebsites.net/path2`), it uses the same hostname in the location header of its response as the one in the request it received from the application gateway. So the client will make the request directly to `contoso.azurewebsites.net/path2` instead of going through the application gateway (`contoso.com/path2`). Bypassing the application gateway isn't desirable.
+
+If in your use case, there are scenarios where the App service will need to send a redirection response to the client, perform the [additional steps to rewrite the location header](./troubleshoot-app-service-redirection-app-service-url.md#sample-configuration).
+
+## Restrict access
+
+The web apps deployed in these examples use public IP addresses that can be  accessed directly from the Internet. This helps with troubleshooting when you are learning about a new feature and trying new things. But if you intend to deploy a feature into production, you'll want to add more restrictions.
+
+One way you can restrict access to your web apps is to use [Azure App Service static IP restrictions](../app-service/app-service-ip-restrictions.md). For example, you can restrict the web app so that it only receives traffic from the application gateway. Use the app service IP restriction feature to list the application gateway VIP as the only address with access.
+
+## Next steps
+
+To learn more about the App service and other multi-tenant support with application gateway, see [multi-tenant service support with application gateway](./application-gateway-web-app-overview.md).

articles/application-gateway/media/configure-web-app-portal/backend-pool.png

@@ -248,12 +248,8 @@
       items:
         - name: Azure portal
           href: rewrite-url-portal.md
-  - name: Configure App service webapp and multi-tenant service
-    items:
-    - name: Portal
-      href: configure-web-app-portal.md
-    - name: Azure PowerShell
-      href: create-web-app.md
+  - name: Configure App Service
+    href: configure-web-app.md
   - name: Configure custom probes
     items:
       - name: Portal

articles/application-gateway/toc.yml

@@ -966,6 +966,15 @@ groups:
     title: C#
   - id: programming-language-python
     title: Python
+# Owner: christoc
+- id: app-service-domainconfig
+  title: Custom domain configuration
+  prompt: Choose your domain name configuration
+  pivots:
+  - id: app-service-domainconfig-defaultdomain
+    title: Default domain
+  - id: app-service-domainconfig-customdomain
+    title: Custom domain
 # Owner: jordanselig
 - id: app-service-cli-portal
   title: Experience