Skip to content

Commit 4678472

Browse files
authored
Add section about TLS renegotiation
1 parent f244f71 commit 4678472

File tree

1 file changed

+22
-19
lines changed

1 file changed

+22
-19
lines changed

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

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,9 @@ For ARM templates, modify the properties `clientCertEnabled`, `clientCertMode`,
9393

9494
When you enable mutual auth for your application, all paths under the root of your app require a client certificate for access. To remove this requirement for certain paths, define exclusion paths as part of your application configuration.
9595

96+
> [!NOTE]
97+
> Using any client certificate exclusion path will trigger TLS renegotiation for the app.
98+
9699
1. From the left navigation of your app's management page, select **Configuration** > **General Settings**.
97100

98101
1. Next to **Certificate exclusion paths**, select the edit icon.
@@ -105,33 +108,33 @@ In the following screenshot, any path for your app that starts with `/public` do
105108

106109
![Certificate Exclusion Paths][exclusion-paths]
107110

108-
## Access client certificate
109-
110-
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.
111+
## Client certificate and TLS renegotiation
112+
App Service requires TLS renegotiation to read a request before knowing whether to prompt for a client certificate. Any of the following settings below will trigger TLS renegotiation:
113+
1. Use "Optional Interactive User" client certificate mode.
114+
1. Use [client certificate exclusion path](#exclusion-paths).
111115

112-
For ASP.NET, the client certificate is available through the **HttpRequest.ClientCertificate** property.
116+
To disable TLS renegotiation and to have the app negotiate client certificates during TLS handshake, you must configure your app with *all* the settings below:
117+
1. Set client certificate mode to "Required" or "Optional"
118+
2. Remove all client certificate exclusion paths
113119

114-
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.
120+
### Uploading large files with TLS renegotiation
121+
Client certificate configurations that uses TLS renegotiation cannot support incoming requests with large files greater than 100kb. TLS renegotiation will fail any POST or PUT requests using large files with a 403 error.
115122

116-
## Client certificate limitation
117-
Certain client certificate configurations cannot support incoming requests with large files greater than 100kb. TLS renegotiation will fail any POST or PUT requests using large files with a 403 error. App Service uses TLS renegotiation to retrieve the client certificates. These configurations below will trigger TLS renegotiation:
123+
To resolve the error due to large files greater than 100kb due to TLS renegotiation, here are known alternative solutions to address the limitations:
118124

119-
1. Using client certificate mode "Optional Interactive User"
120-
2. Using client certificate exclusion paths regardless of client certificate mode
125+
1. Update your app's client certificate configuration to meet _all_ requirements below:
126+
1. Set client certificate mode to either "Required" or "Optional"
127+
1. Remove all client certificate exclusion paths
128+
1. Send a HEAD request before the PUT/POST request. The HEAD request will handle the client certificate.
129+
1. Add the header `Expect: 100-Continue` to your request. This will cause the client to wait until the server responds with a `100 Continue` before sending the request body, which bypasses the buffers.
121130

122-
### Resolving large files limitation
123-
To resolve the error due to large files greater than 100kb due to TLS renegotiation, here are known alternative solutions to address the limitations:
131+
## Access client certificate
124132

125-
#### Changing client certificate configurations
126-
Update your app's client certificate configuration to meet _all_ requirements below:
127-
1. Set client certificate mode to either "Required" or "Optional"
128-
2. Remove all client certificate exclusion paths
133+
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.
129134

130-
#### Sending HEAD requests
131-
Send a HEAD request before the PUT/POST request. The HEAD request will handle the client certificate.
135+
For ASP.NET, the client certificate is available through the **HttpRequest.ClientCertificate** property.
132136

133-
### Adding "Expect:100-Continue" header
134-
Add the header `Expect: 100-Continue` to your request. This will cause the client to wait until the server responds with a `100 Continue` before sending the request body, which bypasses the buffers.
137+
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.
135138

136139
## ASP.NET Core sample
137140

0 commit comments

Comments
 (0)