Merge pull request #112625 from j82w/users/jawilley/macSignature

Add MAC signature and header size issue to .NET troubleshooting guide

Author: ShannonLeavitt

articles/cosmos-db/secure-access-to-data.md

@@ -38,7 +38,15 @@ Primary, secondary, read only, and read-write master keys can be retrieved and r
 
 ![Access control (IAM) in the Azure portal - demonstrating NoSQL database security](./media/secure-access-to-data/nosql-database-security-master-key-portal.png)
 
-The process of rotating your master key is simple. Navigate to the Azure portal to retrieve your secondary key, then replace your primary key with your secondary key in your application, then rotate the primary key in the Azure portal.
+### Key rotation<a id="key-rotation"></a>
+
+The process of rotating your master key is simple. 
+
+1. Navigate to the Azure portal to retrieve your secondary key.
+2. Replace your primary key with your secondary key in your application. Make sure that all the Cosmos DB clients across all the deployments are promptly restarted and will start using the updated key.
+3. Rotate the primary key in the Azure portal.
+4. Validate the new primary key works against all resource. Key rotation process can take any where from less than a minute to hours depending on the size of the Cosmos DB account.
+5. Replace the secondary key with the new primary key.
 
 ![Master key rotation in the Azure portal - demonstrating NoSQL database security](./media/secure-access-to-data/nosql-database-security-master-key-rotate-workflow.png)
 

articles/cosmos-db/troubleshoot-dot-net-sdk.md

@@ -13,7 +13,7 @@ ms.reviewer: sngun
 This article covers common issues, workarounds, diagnostic steps, and tools when you use the [.NET SDK](sql-api-sdk-dotnet.md) with Azure Cosmos DB SQL API accounts.
 The .NET SDK provides client-side logical representation to access the Azure Cosmos DB SQL API. This article describes tools and approaches to help you if you run into any issues.
 
-## Checklist for troubleshooting issues:
+## Checklist for troubleshooting issues
 Consider the following checklist before you move your application to production. Using the checklist will prevent several common issues you might see. You can also quickly diagnose when an issue occurs:
 
 *    Use the latest [SDK](sql-api-sdk-dotnet-standard.md). Preview SDKs should not be used for production. This will prevent hitting known issues that are already fixed.
@@ -95,12 +95,34 @@ The [query metrics](sql-api-query-metrics.md) will help determine where the quer
 * If the back-end query returns quickly, and spends a large time on the client check the load on the machine. It's likely that there are not enough resource and the SDK is waiting for resources to be available to handle the response.
 * If the back-end query is slow try [optimizing the query](optimize-cost-queries.md) and looking at the current [indexing policy](index-overview.md) 
 
+### HTTP 401: The MAC signature found in the HTTP request is not the same as the computed signature
+If you received the following 401 error message: "The MAC signature found in the HTTP request is not the same as the computed signature." it can be caused by the following scenarios.
+
+1. The key was rotated and did not follow the [best practices](secure-access-to-data.md#key-rotation). This is usually the case. Cosmos DB account key rotation can take anywhere from a few seconds to possibly days depending on the Cosmos DB account size.
+   1. 401 MAC signature is seen shortly after a key rotation and eventually stops without any changes. 
+2. The key is misconfigured on the application so the key does not match the account.
+   1. 401 MAC signature issue will be consistent and happens for all calls
+3. There is a race condition with container creation. An application instance is trying to access the container before container creation is complete. The most common scenario for this if the application is running, and the container is deleted and recreated with the same name while the application is running. The SDK will attempt to use the new container, but the container creation is still in progress so it does not have the keys.
+   1. 401 MAC signature issue is seen shortly after a container creation, and only occur until the container creation is completed.
+ 
+ ### HTTP Error 400. The size of the request headers is too long.
+ The size of the header has grown to large and is exceeding the maximum allowed size. It's always recommended to use the latest SDK. Make sure to use at least version [3.x](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/changelog.md) or [2.x](https://github.com/Azure/azure-cosmos-dotnet-v2/blob/master/changelog.md), which adds header size tracing to the exception message.
+
+Causes:
+ 1. The session token has grown too large. The session token grows as the number of partitions increase in the container.
+ 2. The continuation token has grown to large. Different queries will have different continuation token sizes.
+ 3. It's caused by a combination of the session token and continuation token.
+
+Solution:
+   1. Follow the [performance tips](performance-tips.md) and convert the application to Direct + TCP connection mode. Direct + TCP does not have the header size restriction like HTTP does which avoids this issue.
+   2. If the session token is the cause, then a temporary mitigation is to restart the application. Restarting the application instance will reset the session token. If the exceptions stop after the restart, then it confirms the session token is the cause. It will eventually grow back to the size that will cause the exception.
+   3. If the application cannot be converted to Direct + TCP and the session token is the cause, then mitigation can be done by changing the client [consistency level](consistency-levels.md). The session token is only used for session consistency which is the default for Cosmos DB. Any other consistency level will not use the session token. 
+   4. If the application cannot be converted to Direct + TCP and the continuation token is the cause, then try setting the ResponseContinuationTokenLimitInKb option. The option can be found in the FeedOptions for v2 or the QueryRequestOptions in v3.
+
  <!--Anchors-->
 [Common issues and workarounds]: #common-issues-workarounds
 [Enable client SDK logging]: #logging
 [Request rate too large]: #request-rate-too-large
 [Request Timeouts]: #request-timeouts
 [Azure SNAT (PAT) port exhaustion]: #snat
 [Production check list]: #production-check-list
-
-