Merge pull request #217599 from PatrickFarley/cogserv

[cog svcs] add key rotation doc

Author: v-stsavell

articles/cognitive-services/TOC.yml

@@ -75,6 +75,8 @@
       href: security-features.md
     - name: Authenticate requests to Cognitive Services
       href: authentication.md
+    - name: Rotate keys
+      href: rotate-keys.md
     - name: Use environment variables with Cognitive Services
       href: cognitive-services-environment-variables.md
     - name: Configure customer-managed keys

articles/cognitive-services/cognitive-services-limited-access.md

@@ -96,6 +96,10 @@ Detailed information about supported regions for Custom Neural Voice and Speaker
 
 If you're an existing customer and your application for access is denied, you will no longer be able to use Limited Access features after June 30, 2023. Your data is subject to Microsoft's data retention [policies](https://www.microsoft.com/trust-center/privacy/data-management#:~:text=If%20you%20terminate%20a%20cloud,data%20or%20renew%20your%20subscription.). 
 
+### How long will the registration process take?
+
+You'll receive communication from us about your application within 10 business days. In some cases, reviews can take longer. You'll receive an email as soon as your application is reviewed.
+
 ## Help and support 
 
 Report abuse of Limited Access services [here](https://aka.ms/reportabuse).

articles/cognitive-services/rotate-keys.md

@@ -0,0 +1,35 @@
+---
+title: Rotate keys in Azure Cognitive Services
+titleSuffix: Azure Cognitive Services
+description: "Learn how to rotate API keys for better security, without interrupting service"
+services: cognitive-services
+author: PatrickFarley
+manager: nitinme
+ms.service: cognitive-services
+ms.topic: how-to
+ms.date: 11/08/2022
+ms.author: pafarley
+---
+
+# Rotate subscription keys in Cognitive Services
+
+Each Cognitive Services resource has two API keys to enable secret rotation. This is a security precaution that lets you regularly change the keys that can access your service, protecting the privacy of your resource if a key gets leaked.
+
+## How to rotate keys
+
+Keys can be rotated using the following procedure:
+ 
+1. If you're using both keys in production, change your code so that only one key is in use. In this guide, assume it's key 1.
+
+   This is a necessary step because once a key is regenerated, the older version of that key will stop working immediately. This would cause clients using the older key to get 401 access denied errors.
+1. Once you have only key 1 in use, you can regenerate the key 2. Go to your resource's page on the Azure portal, select the **Keys and Endpoint** tab, and select the **Regenerate Key 2** button at the top of the page.
+1. Next, update your code to use the newly generated key 2.
+
+   It will help to have logs or availability to check that users of the key have successfully swapped from using key 1 to key 2 before you proceed.
+1. Now you can regenerate the key 1 using the same process.
+1. Finally, update your code to use the new key 1. 
+
+## See also
+
+* [What is Cognitive Services?](./what-are-cognitive-services.md)
+* [Cognitive Services security features](./security-features.md)

articles/cognitive-services/security-features.md

@@ -24,6 +24,7 @@ For a comprehensive list of Azure service security recommendations see the [Cogn
 |:---|:---|
 | [Transport Layer Security (TLS)](/dotnet/framework/network-programming/tls) | All of the Cognitive Services endpoints exposed over HTTP enforce the TLS 1.2 protocol. With an enforced security protocol, consumers attempting to call a Cognitive Services endpoint should follow these guidelines: </br>- The client operating system (OS) needs to support TLS 1.2.</br>- The language (and platform) used to make the HTTP call need to specify TLS 1.2 as part of the request. Depending on the language and platform, specifying TLS is done either implicitly or explicitly.</br>- For .NET users, consider the [Transport Layer Security best practices](/dotnet/framework/network-programming/tls). |
 | [Authentication options](./authentication.md)| Authentication is the act of verifying a user's identity. Authorization, by contrast, is the specification of access rights and privileges to resources for a given identity. An identity is a collection of information about a <a href="https://en.wikipedia.org/wiki/Principal_(computer_security)" target="_blank">principal</a>, and a principal can be either an individual user or a service.</br></br>By default, you authenticate your own calls to Cognitive Services using the subscription keys provided; this is the simplest method but not the most secure. The most secure authentication method is to use managed roles in Azure Active Directory. To learn about this and other authentication options, see [Authenticate requests to Cognitive Services](./authentication.md). |
+| [Key rotation](./authentication.md)| Each Cognitive Services resource has two API keys to enable secret rotation. This is a security precaution that lets you regularly change the keys that can access your service, protecting the privacy of your service in the event that a key gets leaked. To learn about this and other authentication options, see [Rotate keys](/azure/cognitive-services/rotate-keys). |
 | [Environment variables](cognitive-services-environment-variables.md) | Environment variables are name-value pairs that are stored within a specific development environment. You can store your credentials in this way as a more secure alternative to using hardcoded values in your code. However, if your environment is compromised, the environment variables are compromised as well, so this is not the most secure approach.</br></br> For instructions on how to use environment variables in your code, see the [Environment variables guide](cognitive-services-environment-variables.md). |
 | [Customer-managed keys (CMK)](./encryption/cognitive-services-encryption-keys-portal.md) | This feature is for services that store customer data at rest (longer than 48 hours). While this data is already double-encrypted on Azure servers, users can get extra security by adding another layer of encryption, with keys they manage themselves. You can link your service to Azure Key Vault and manage your data encryption keys there. </br></br>You need special approval to get the E0 SKU for your service, which enables CMK. Within 3-5 business days after you submit the [request form](https://aka.ms/cogsvc-cmk), you'll get an update on the status of your request. Depending on demand, you may be placed in a queue and approved as space becomes available. Once you're approved for using the E0 SKU, you'll need to create a new resource from the Azure portal and select E0 as the Pricing Tier. You won't be able to upgrade from F0 to the new E0 SKU. </br></br>Only some services can use CMK; look for your service on the [Customer-managed keys](./encryption/cognitive-services-encryption-keys-portal.md) page.|
 | [Virtual networks](./cognitive-services-virtual-networks.md) | Virtual networks allow you to specify which endpoints can make API calls to your resource. The Azure service will reject API calls from devices outside of your network. You can set a formula-based definition of the allowed network, or you can define an exhaustive list of endpoints to allow. This is another layer of security that can be used in combination with others. |