edits

Author: ktoliver

articles/app-service/app-service-web-configure-tls-mutual-auth.md

@@ -1,6 +1,6 @@
 ---
-title: Set up TLS mutual authentication
-description: Learn how to set up TLS mutual authentication in Azure App Service for secure two-way communication between client and server.
+title: Set Up TLS mutual authentication
+description: Learn how to set up TLS mutual authentication in Azure App Service to help secure two-way communication between client and server.
 keywords: TLS mutual authentication, Azure App Service security, secure client-server communication
 author: msangapu-msft
 ms.author: msangapu
@@ -12,38 +12,44 @@ ms.custom: devx-track-csharp, devx-track-extended-java, devx-track-js, devx-trac
 ---
 # Configure TLS mutual authentication in Azure App Service
 
-You can restrict access to your Azure App Service app by enabling different types of authentication for it. One way to do it is to request a client certificate when the client request is over TLS/SSL and validate the certificate. This mechanism is called Transport Layer Security (TLS) mutual authentication or client certificate authentication. This article shows how to set up your app to use client certificate authentication.
+You can restrict access to your Azure App Service app by enabling different types of authentication for it. One way to set up authentication is to request a client certificate when the client request is over TLS/SSL and to validate the certificate. This mechanism is called Transport Layer Security (TLS) mutual authentication or client certificate authentication. This article shows how to set up your app to use client certificate authentication.
 
 > [!NOTE]
 > Your app code is responsible for validating the client certificate. App Service doesn't do anything with this client certificate other than forwarding it to your app.
-> 
-> If you access your site over HTTP and not HTTPS, you will not receive any client certificate. So if your application requires client certificates, you should not allow requests to your application over HTTP.
+>
+> If you access your site over HTTP and not HTTPS, you don't receive any client certificates. If your application requires client certificates, you shouldn't allow requests to your application over HTTP.
 
 [!INCLUDE [Prepare your web app](../../includes/app-service-ssl-prepare-app.md)]
 
 ## Enable client certificates
-When you enable client certificate for your app, you should select your choice of client certificate mode. Each mode defines how your app handles incoming client certificates:
 
-|Client certificate modes|Description|
+When you enable client certificates for your app, you should select your choice of client certificate mode. Each mode defines how your app handles incoming client certificates.
+
+|Client certificate mode|Description|
 |-|-|
 |Required|All requests require a client certificate.|
-|Optional|Requests may or may not use a client certificate and clients are prompted for a certificate by default. For example, browser clients will show a prompt to select a certificate for authentication.|
-|Optional Interactive User|Requests may or may not use a client certificate and clients are not prompted for a certificate by default. For example, browser clients won't show a prompt to select a certificate for authentication.|
+|Optional|Requests can use a client certificate and clients are prompted for a certificate by default. For example, browser clients show a prompt to select a certificate for authentication.|
+|Optional Interactive User|Requests can use a client certificate and clients aren't prompted for a certificate by default. For example, browser clients don't show a prompt to select a certificate for authentication.|
 
 ### [Azure portal](#tab/azureportal)
-To set up your app to require client certificates in Azure portal:
-1. Navigate to your app's management page.
-1. From the left navigation of your app's management page, select **Configuration** > **General Settings**.
-1. Select **Client certificate mode** of choice. Select **Save** at the top of the page.
+
+To set up your app to require client certificates in the Azure portal:
+
+1. Go to your app management page.
+1. On the resource menu, select **Configuration** > **General Settings**.
+1. For **Client certificate mode**, select your choice.
+1. Select **Save**.
 
 ### [Azure CLI](#tab/azurecli)
-With Azure CLI, run the following command in the [Cloud Shell](https://shell.azure.com):
+
+With the Azure CLI, run the following command in the [Cloud Shell](https://shell.azure.com):
 
 ```azurecli-interactive
 az webapp update --set clientCertEnabled=true --name <app-name> --resource-group <group-name>
 ```
 
 ### [Bicep](#tab/bicep)
+
 For Bicep, modify the properties `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths`. A sample Bicep snippet is provided for you:
 
 ```bicep
@@ -64,7 +70,8 @@ resource appService 'Microsoft.Web/sites@2020-06-01' = {
 ```
 
 ### [ARM template](#tab/arm)
-For ARM templates, modify the properties `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths`. A sample ARM template snippet is provided for you:
+
+For Azure Resource Manager templates (ARM templates), modify the properties `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths`. A sample ARM template snippet is provided for you:
 
 ```ARM
 {
@@ -96,48 +103,52 @@ When you enable mutual auth for your application, all paths under the root of yo
 > [!NOTE]
 > Using any client certificate exclusion path triggers TLS renegotiation for incoming requests to the app.
 
-1. From the left navigation of your app's management page, select **Configuration** > **General Settings**.
+1. On the resource menu of your app's management pane, select **Configuration** > **General Settings**.
 
 1. Next to **Certificate exclusion paths**, select the edit icon.
 
 1. Select **New path**, specify a path, or a list of paths separated by `,` or `;`, and select **OK**.
 
-1. Select **Save** at the top of the page.
+1. Select **Save**.
 
 In the following screenshot, any path for your app that starts with `/public` doesn't request a client certificate. Path matching is case-insensitive.
 
 ![Certificate Exclusion Paths][exclusion-paths]
 
 ## Client certificate and TLS renegotiation
+
 For some client certificate settings, App Service requires TLS renegotiation to read a request before knowing whether to prompt for a client certificate. Any of the following settings triggers TLS renegotiation:
-1. Using "Optional Interactive User" client certificate mode.
-1. Using [client certificate exclusion path](#exclude-paths-from-requiring-authentication).
+
+- Using the "Optional Interactive User" client certificate mode.
+- Using the [client certificate exclusion path](#exclude-paths-from-requiring-authentication).
 
 > [!NOTE]
-> TLS 1.3 and HTTP 2.0 don't support TLS renegotiation. These protocols will not work if your app is configured with client certificate settings that use TLS renegotiation.
+> TLS 1.3 and HTTP 2.0 don't support TLS renegotiation. These protocols don't work if your app is configured with client certificate settings that use TLS renegotiation.
 
 To disable TLS renegotiation and to have the app negotiate client certificates during TLS handshake, you must configure your app with *all* these settings:
-1. Set client certificate mode to "Required" or "Optional"
-2. Remove all client certificate exclusion paths
 
-### Uploading large files with TLS renegotiation
-Client certificate configurations that use TLS renegotiation cannot support incoming requests with large files greater than 100 kb due to buffer size limitations. In this scenario, any POST or PUT requests over 100 kb will fail with a 403 error. This limit isn't configurable and can't be increased.
+1. Set client certificate mode to "Required" or "Optional."
+1. Remove all client certificate exclusion paths.
+
+### Upload large files with TLS renegotiation
 
-To address the 100 kb limit, consider these alternative solutions:
+Client certificate configurations that use TLS renegotiation can't support incoming requests with large files greater than 100 KB due to buffer size limitations. In this scenario, any POST or PUT requests over 100 KB fails with a 403 error. This limit isn't configurable and can't be increased.
 
-1. Disable TLS renegotiation. Update your app's client certificate configurations with _all_ these settings:
-    - Set client certificate mode to either "Required" or "Optional"
-    - Remove all client certificate exclusion paths
+To address the 100-KB limit, consider these alternative solutions:
+
+1. Disable TLS renegotiation. Update your app's client certificate configurations with *all* these settings:
+    - Set the client certificate mode to either "Required" or "Optional."
+    - Remove all client certificate exclusion paths.
 1. Send a HEAD request before the PUT/POST request. The HEAD request handles the client certificate.
 1. Add the header `Expect: 100-Continue` to your request. This causes the client to wait until the server responds with a `100 Continue` before sending the request body, which bypasses the buffers.
 
 ## Access client certificate
 
 In App Service, TLS termination of the request happens at the frontend load balancer. When App Service forwards the request to your app code with [client certificates enabled](#enable-client-certificates), it injects an `X-ARR-ClientCert` request header with the client certificate. App Service doesn't do anything with this client certificate other than forwarding it to your app. Your app code is responsible for validating the client certificate.
 
-For ASP.NET, the client certificate is available through the **HttpRequest.ClientCertificate** property.
+For ASP.NET, the client certificate is available through the `HttpRequest.ClientCertificate` property.
 
-For other application stacks (Node.js, PHP, etc.), the client cert is available in your app through a base64 encoded value in the `X-ARR-ClientCert` request header.
+For other application stacks (Node.js, PHP, etc.), the client cert is available in your app through a base64-encoded value in the `X-ARR-ClientCert` request header.
 
 ## ASP.NET Core sample
 
@@ -273,22 +284,22 @@ public class Startup
             //
             private bool IsValidClientCertificate()
             {
-                // In this example we will only accept the certificate as a valid certificate if all the conditions below are met:
-                // 1. The certificate isn't expired and is active for the current time on server.
-                // 2. The subject name of the certificate has the common name nildevecc
-                // 3. The issuer name of the certificate has the common name nildevecc and organization name Microsoft Corp
-                // 4. The thumbprint of the certificate is 30757A2E831977D8BD9C8496E4C99AB26CB9622B
+                // In this example, we accept the certificate as a valid certificate only if all the conditions below are met:
+                // - The certificate isn't expired and is active for the current time on the server.
+                // - The subject name of the certificate has the common name nildevecc.
+                // - The issuer name of the certificate has the common name nildevecc and the organization name Microsoft Corp.
+                // - The thumbprint of the certificate is 30757A2E831977D8BD9C8496E4C99AB26CB9622B.
                 //
                 // This example doesn't test that this certificate is chained to a Trusted Root Authority (or revoked) on the server 
-                // and it allows for self signed certificates
+                // and it allows for self-signed certificates.
                 //
 
                 if (certificate == null || !String.IsNullOrEmpty(errorString)) return false;
 
-                // 1. Check time validity of certificate
+                // 1. Check time validity of the certificate.
                 if (DateTime.Compare(DateTime.Now, certificate.NotBefore) < 0 || DateTime.Compare(DateTime.Now, certificate.NotAfter) > 0) return false;
 
-                // 2. Check subject name of certificate
+                // 2. Check the subject name of the certificate.
                 bool foundSubject = false;
                 string[] certSubjectData = certificate.Subject.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries);
                 foreach (string s in certSubjectData)
@@ -301,7 +312,7 @@ public class Startup
                 }
                 if (!foundSubject) return false;
 
-                // 3. Check issuer name of certificate
+                // 3. Check the issuer name of the certificate.
                 bool foundIssuerCN = false, foundIssuerO = false;
                 string[] certIssuerData = certificate.Issuer.Split(new char[] { ',' }, StringSplitOptions.RemoveEmptyEntries);
                 foreach (string s in certIssuerData)
@@ -321,7 +332,7 @@ public class Startup
 
                 if (!foundIssuerCN || !foundIssuerO) return false;
 
-                // 4. Check thumbprint of certificate
+                // 4. Check the thumbprint of the certificate.
                 if (String.Compare(certificate.Thumbprint.Trim().ToUpper(), "30757A2E831977D8BD9C8496E4C99AB26CB9622B") != 0) return false;
 
                 return true;
@@ -332,7 +343,7 @@ public class Startup
 
 ## Node.js sample
 
-The following Node.js sample code gets the `X-ARR-ClientCert` header and uses [node-forge](https://github.com/digitalbazaar/forge) to convert the base64-encoded PEM string into a certificate object and validate it:
+The following Node.js sample code gets the `X-ARR-ClientCert` header and uses [node-forge](https://github.com/digitalbazaar/forge) to convert the base64-encoded Privacy Enhanced Mail (PEM) string into a certificate object and validate it:
 
 ```javascript
 import { NextFunction, Request, Response } from 'express';
@@ -377,8 +388,7 @@ export class AuthorizationHandler {
 
 ## Java sample
 
-The following Java class encodes the certificate from `X-ARR-ClientCert` to an `X509Certificate` instance. `certificateIsValid()` validates that the certificate's thumbprint matches the one given in the constructor and that certificate hasn't expired.
-
+The following Java class encodes the certificate from `X-ARR-ClientCert` to an `X509Certificate` instance. `certificateIsValid()` validates that the certificate's thumbprint matches the one given in the constructor and that certificate isn't expired.
 
 ```java
 import java.io.ByteArrayInputStream;