updates

Author: v-albemi

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

@@ -26,34 +26,34 @@ You can restrict access to your Azure App Service app by enabling various types
 
 ## Enable client certificates
 
-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.
+When you enable client certificates for your app, you should select your choice of client certificate mode. The mode defines how your app handles incoming client certificates. The modes are described in the following table:
 
 |Client certificate mode|Description|
 |-|-|
 |Required|All requests require a client certificate.|
-|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.|
+|Optional|Requests can use a client certificate. 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. 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 use the Azure portal to set up your app to require client certificates:
+To use the Azure portal to enable client certificates:
 
 1. Go to your app management page.
-1. On the left menu, select **Configuration** > **General Settings**.
+1. In the left menu, select **Configuration** > **General Settings**.
 1. For **Client certificate mode**, select your choice.
 1. Select **Save**.
 
 ### [Azure CLI](#tab/azurecli)
 
-To use the Azure CLI, run the following command in [Azure Cloud Shell](https://shell.azure.com):
+To use the Azure CLI to enable client certificates, run the following command in [Azure 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 `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths` properties.
+To enable client certificates in Bicep, modify the `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths` properties.
 
 Here's a sample Bicep snippet:
 
@@ -76,7 +76,7 @@ resource appService 'Microsoft.Web/sites@2020-06-01' = {
 
 ### [ARM template](#tab/arm)
 
-For Azure Resource Manager templates (ARM templates), modify the `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths` properties.
+To enable client certificates in an Azure Resource Manager template (ARM template), modify the `clientCertEnabled`, `clientCertMode`, and `clientCertExclusionPaths` properties.
 
 Here's a sample ARM template snippet:
 
@@ -110,56 +110,56 @@ When you enable mutual authentication for your application, all paths under the
 > [!NOTE]
 > Using any client certificate exclusion path triggers TLS renegotiation for incoming requests to the app.
 
-1. On the left menu of your app management page, select **Configuration** > **General Settings**.
+1. In the left menu of your app management page, 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 then select **OK**.
 
 1. Select **Save**.
 
-In the following screenshot, any path for your app that starts with `/public` doesn't request a client certificate. Path matching isn't case specific.
+The following screenshot shows how to set a certificate exclusion path. Any path for the app that starts with `/public` doesn't request a client certificate. Path matching isn't case specific.
 
-:::image type="content" source="media/app-service-web-configure-tls-mutual-auth/exclusion-paths.png" alt-text="Screenshot that shows setting a certificate exclusion path.":::
+:::image type="content" source="media/app-service-web-configure-tls-mutual-auth/exclusion-paths.png" alt-text="Screenshot that shows how to set a certificate exclusion path." lightbox="media/app-service-web-configure-tls-mutual-auth/exclusion-paths.png":::
 
 ## 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:
+For some client certificate settings, App Service requires TLS renegotiation to read a request before knowing whether to prompt for a client certificate. Both of the following settings trigger TLS renegotiation:
 
-- Using the "Optional Interactive User" client certificate mode.
-- Using the [client certificate exclusion path](#exclude-paths-from-requiring-authentication).
+- Using the **Optional Interactive User** client certificate mode.
+- Using a [client certificate exclusion path](#exclude-paths-from-requiring-authentication).
 
 > [!NOTE]
 > 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:
+To disable TLS renegotiation and have the app negotiate client certificates during TLS handshake, you must take the following actions in your app:
 
-1. Set the client certificate mode to **Required** or **Optional**.
-1. Remove all client certificate exclusion paths.
+- Set the client certificate mode to **Required** or **Optional**.
+- Remove all client certificate exclusion paths.
 
 ### Upload large files with TLS renegotiation
 
-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.
+Client certificate configurations that use TLS renegotiation can't support incoming requests with files that are larger than 100 KB. This limit is caused by buffer size limitations. In this scenario, any POST or PUT requests that are over 100 KB fail with a 403 error. This limit isn't configurable and can't be increased.
 
-To address the 100-KB limit, consider these alternative solutions:
+To address the 100-KB limit, consider these solutions:
 
-1. Disable TLS renegotiation. Update your app's client certificate configurations with *all* these settings:
+1. Disable TLS renegotiation. Take the following actions in your app's client certificate configurations:
     - Set the client certificate mode to **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.
+1. Add the header `Expect: 100-Continue` to your request. This header causes the client to wait until the server responds with a `100 Continue` before sending the request body, and the buffers are bypassed.
 
 ## Access the client certificate
 
-In App Service, TLS termination of the request happens at the front-end 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 forward it to your app. Your app code is responsible for validating the client certificate.
+In App Service, TLS termination of the request happens at the front-end 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 forward it to your app. Your app code needs to validate the client certificate.
 
-For ASP.NET, the client certificate is available through the `HttpRequest.ClientCertificate` property.
+In ASP.NET, the client certificate is available through the `HttpRequest.ClientCertificate` property.
 
-For other application stacks (Node.js, PHP), the client certificate is available in your app through a Base64-encoded value in the `X-ARR-ClientCert` request header.
+In other application stacks (Node.js, PHP), the client certificate is available via a Base64-encoded value in the `X-ARR-ClientCert` request header.
 
 ## ASP.NET Core sample
 
-For ASP.NET Core, middleware is provided to parse forwarded certificates. Separate middleware is provided to use the forwarded protocol headers. Both must be present for forwarded certificates to be accepted. You can place custom certificate validation logic in the [CertificateAuthentication options](/aspnet/core/security/authentication/certauth).
+For ASP.NET Core, middleware is available to parse forwarded certificates. Separate middleware is available for using the forwarded protocol headers. Both must be present for forwarded certificates to be accepted. You can place custom certificate validation logic in the [CertificateAuthentication options](/aspnet/core/security/authentication/certauth):
 
 ```csharp
 public class Startup
@@ -174,20 +174,20 @@ public class Startup
     public void ConfigureServices(IServiceCollection services)
     {
         services.AddControllersWithViews();
-        // Configure the application to use the protocol and client ip address forwarded by the front-end load balancer
+        // Configure the application to use the protocol and client IP address forwarded by the front-end load balancer.
         services.Configure<ForwardedHeadersOptions>(options =>
         {
             options.ForwardedHeaders =
                 ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
-            // Only loopback proxies are allowed by default. Clear that restriction to enable this explicit configuration.
+            // By default, only loopback proxies are allowed. Clear that restriction to enable this explicit configuration.
             options.KnownNetworks.Clear();
             options.KnownProxies.Clear();
         });       
 
-        // Configure the application to client certificate forwarded the front-end load balancer
+        // Configure the application to use the client certificate forwarded by the front-end load balancer.
         services.AddCertificateForwarding(options => { options.CertificateHeader = "X-ARR-ClientCert"; });
 
-        // Add certificate authentication so when authorization is performed the user will be created from the certificate
+        // Add certificate authentication so that  when authorization is performed the user will be created from the certificate.
         services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme).AddCertificate();
     }
 
@@ -224,7 +224,7 @@ public class Startup
 }
 ```
 
-## ASP.NET WebForms sample
+## ASP.NET Web Forms sample
 
 ```csharp
     using System;
@@ -248,8 +248,8 @@ public class Startup
             public bool isValidCert = false;
 
             //
-            // Read the certificate from the header into an X509Certificate2 object
-            // Display properties of the certificate on the page
+            // Read the certificate from the header into an X509Certificate2 object.
+            // Display properties of the certificate on the page.
             //
             protected void Page_Load(object sender, EventArgs e)
             {
@@ -286,19 +286,19 @@ public class Startup
             }
 
             //
-            // This is a SAMPLE verification routine. Depending on your application logic and security requirements, 
-            // you should modify this method
+            // This is a sample verification routine. You should modify this method to suit  your application logic and security requirements. 
+            // 
             //
             private bool IsValidClientCertificate()
             {
-                // In this example, we accept the certificate as a valid certificate only if all the conditions below are met:
+                // In this example, the certificate is accepted as a valid certificate only if these conditions 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.
+                // This example doesn't test that the certificate is chained to a trusted root authority (or revoked) on the server. 
+                // It allows self-signed certificates.
                 //
 
                 if (certificate == null || !String.IsNullOrEmpty(errorString)) return false;
@@ -359,26 +359,26 @@ import { pki, md, asn1 } from 'node-forge';
 export class AuthorizationHandler {
     public static authorizeClientCertificate(req: Request, res: Response, next: NextFunction): void {
         try {
-            // Get header
+            // Get header.
             const header = req.get('X-ARR-ClientCert');
             if (!header) throw new Error('UNAUTHORIZED');
 
-            // Convert from PEM to pki.CERT
+            // Convert from PEM to PKI certificate.
             const pem = `-----BEGIN CERTIFICATE-----${header}-----END CERTIFICATE-----`;
             const incomingCert: pki.Certificate = pki.certificateFromPem(pem);
 
-            // Validate certificate thumbprint
+            // Validate certificate thumbprint.
             const fingerPrint = md.sha1.create().update(asn1.toDer(pki.certificateToAsn1(incomingCert)).getBytes()).digest().toHex();
             if (fingerPrint.toLowerCase() !== 'abcdef1234567890abcdef1234567890abcdef12') throw new Error('UNAUTHORIZED');
 
-            // Validate time validity
+            // Validate time validity.
             const currentDate = new Date();
             if (currentDate < incomingCert.validity.notBefore || currentDate > incomingCert.validity.notAfter) throw new Error('UNAUTHORIZED');
 
-            // Validate issuer
+            // Validate issuer.
             if (incomingCert.issuer.hash.toLowerCase() !== 'abcdef1234567890abcdef1234567890abcdef12') throw new Error('UNAUTHORIZED');
 
-            // Validate subject
+            // Validate subject.
             if (incomingCert.subject.hash.toLowerCase() !== 'abcdef1234567890abcdef1234567890abcdef12') throw new Error('UNAUTHORIZED');
 
             next();
@@ -416,9 +416,9 @@ public class ClientCertValidator {
 
     /**
      * Constructor.
-     * @param certificate The certificate from the "X-ARR-ClientCert" HTTP header
-     * @param thumbprint The thumbprint to check against
-     * @throws CertificateException If the certificate factory cannot be created.
+     * @param certificate. The certificate from the "X-ARR-ClientCert" HTTP header.
+     * @param thumbprint. The thumbprint to check against.
+     * @throws CertificateException if the certificate factory can't be created.
      */
     public ClientCertValidator(String certificate, String thumbprint) throws CertificateException {
         certificate = certificate
@@ -434,16 +434,16 @@ public class ClientCertValidator {
 
     /**
      * Check that the certificate's thumbprint matches the one given in the constructor, and that the
-     * certificate hasn't expired.
-     * @return True if the certificate's thumbprint matches and hasn't expired. False otherwise.
+     * certificate isn't expired.
+     * @return True if the certificate's thumbprint matches and isn't expired. False otherwise.
      */
     public boolean certificateIsValid() throws NoSuchAlgorithmException, CertificateEncodingException {
         return certificateHasNotExpired() && thumbprintIsValid();
     }
 
     /**
      * Check certificate's timestamp.
-     * @return Returns true if the certificate hasn't expired. Returns false if it has expired.
+     * @return returns True if the certificate isn't expired. It returns False if it is expired.
      */
     private boolean certificateHasNotExpired() {
         Date currentTime = new java.util.Date();
@@ -456,8 +456,8 @@ public class ClientCertValidator {
     }
 
     /**
-     * Check the certificate's thumbprint matches the given one.
-     * @return Returns true if the thumbprints match. False otherwise.
+     * Check whether the certificate's thumbprint matches the given one.
+     * @return returns True if the thumbprints match. False otherwise.
      */
     private boolean thumbprintIsValid() throws NoSuchAlgorithmException, CertificateEncodingException {
         MessageDigest md = MessageDigest.getInstance("SHA-1");
@@ -468,7 +468,7 @@ public class ClientCertValidator {
         return digestHex.toLowerCase().equals(this.getThumbprint().toLowerCase());
     }
 
-    // Getters and setters
+    // Getters and setters.
 
     public void setThumbprint(String thumbprint) {
         this.thumbprint = thumbprint;
@@ -490,7 +490,7 @@ public class ClientCertValidator {
 
 ## Python sample
 
-The following Flask and Django Python code samples implement a decorator named `authorize_certificate` that can be used on a view function to permit access only to callers that present a valid client certificate. It expects a PEM formatted certificate in the `X-ARR-ClientCert` header and uses the Python [cryptography](https://pypi.org/project/cryptography/) package to validate the certificate based on its fingerprint (thumbprint), subject common name, issuer common name, and beginning and expiration dates. If validation fails, the decorator ensures that an HTTP response with status code 403 (Forbidden) is returned to the client.
+The following Flask and Django Python code samples implement a decorator named `authorize_certificate` that can be used on a view function to permit access only to callers that present a valid client certificate. It expects a PEM-formatted certificate in the `X-ARR-ClientCert` header and uses the Python [cryptography](https://pypi.org/project/cryptography/) package to validate the certificate based on its fingerprint (thumbprint), subject common name, issuer common name, and beginning and expiration dates. If validation fails, the decorator ensures that an HTTP response with status code 403 (Forbidden) is returned to the client.
 
 ### [Flask](#tab/flask)
 
@@ -538,7 +538,7 @@ def validate_cert(request):
         return True
 
     except Exception as e:
-        # Handle any errors encountered during validation
+        # Handle any errors encountered during validation.
         print(f"Encountered the following error during certificate validation: {e}")
         return False
 
@@ -607,7 +607,7 @@ def validate_cert(request):
         return True
 
     except Exception as e:
-        # Handle any errors encountered during validation
+        # Handle any errors encountered during validation.
         print(f"Encountered the following error during certificate validation: {e}")
         return False