Merge pull request #223822 from HeidiSteen/heidist-rbac

[azure search] RBAC-related updates

Author: prmerger-automator[bot]

articles/search/search-manage.md

@@ -9,7 +9,7 @@ ms.author: heidist
 tags: azure-portal
 ms.service: cognitive-search
 ms.topic: conceptual
-ms.date: 12/21/2022
+ms.date: 01/12/2023
 ---
 # Service administration for Azure Cognitive Search in the Azure portal
 
@@ -62,8 +62,8 @@ Several aspects of a search service are determined when the service is provision
 Service administration includes the following tasks:
 
 * [Adjust capacity](search-capacity-planning.md) by adding or removing replicas and partitions
-* [Rotate API keys](search-security-api-keys.md) used for admin and query operations
-* [Control access to admin operations](search-security-rbac.md) through role-based security
+* [Manage API keys](search-security-api-keys.md) used for admin and query operations
+* [Allow or deny access using Azure roles](search-security-rbac.md)
 * [Configure IP firewall rules](service-configure-firewall.md) to restrict access by IP address
 * [Configure a private endpoint](service-create-private-endpoint.md) using Azure Private Link and a private virtual network
 * [Monitor service health and operations](monitor-azure-cognitive-search.md): storage, query volumes, and latency
@@ -92,22 +92,24 @@ Internally, Microsoft collects telemetry data about your service and the platfor
 | Telemetry | One and a half years |
 
 > [!NOTE]
-> This section is about monitoring data. For questions about customer data and privacy, see the ["Data residency"](search-security-overview.md#data-residency) section of the security overview article.
+> See the ["Data residency"](search-security-overview.md#data-residency) section of the security overview article for more information about data location and privacy.
 
 ## Administrator permissions
 
 When you open the search service overview page, the Azure role assigned to your account determines what portal content is available to you. The overview page at the beginning of the article shows the portal content available to an Owner or Contributor.
 
-Control plane roles include the following items:
+Azure roles used for service administration include:
 
 * Owner
 * Contributor (same as Owner, minus the ability to assign roles)
-* Reader (access to service information and the Monitoring tab)
+* Reader (provides access to service information in the Essentials section and in the Monitoring tab)
 
-If you want a combination of control plane and data plane permissions, consider Search Service Contributor. For more information, see [Built-in roles](search-security-rbac.md#built-in-roles-used-in-search).
+By default, all search services start with at least one Owner. Owners, service administrators, and co-administrators have permission to create other administrators and other role assignments.
+
+Also by default, search services start with API keys for content-related tasks that an Owner or Contributor might perform in the portal. However, it's possible to turn off [API key authentication](search-security-api-keys.md) and use [Azure role-based access control](search-security-rbac.md#built-in-roles-used-in-search) exclusively. If you turn off API keys, be sure to set up data access role assignments so that all features in the portal remain operational.
 
 > [!TIP]
-> By default, any Owner or Co-owner can create or delete services. To prevent accidental deletions, you can  [lock resources](../azure-resource-manager/management/lock-resources.md).
+> By default, any owner or administrator can create or delete services. To prevent accidental deletions, you can [lock resources](../azure-resource-manager/management/lock-resources.md).
 
 ## Next steps
 

articles/search/search-security-api-keys.md

@@ -1,5 +1,5 @@
 ---
-title: Connect with API keys
+title: Connect using API keys
 titleSuffix: Azure Cognitive Search
 description: Learn how to use an admin or query API key for inbound access to an Azure Cognitive Search service endpoint.
 
@@ -15,10 +15,10 @@ ms.date: 01/10/2023
 
 Cognitive Search offers key-based authentication that you can use on connections to your search service. An API key is a unique string composed of 52 randomly generated numbers and letters. A request made to a search service endpoint will be accepted if both the request and the API key are valid.
 
-API keys are frequently used when making REST API calls to a search service. You can also use them in search solutions if Azure Active Directory isn't an option.
+API keys are used for content-related requests, such as creating or querying an index. Upon service creation, it's the only authentication mechanism for data plane (content) operations, but you can replace or supplement key authentication with [Azure roles](search-security-rbac.md) if you can't use hard-coded keys in your code.
 
 > [!NOTE]
-> A quick note about "key" terminology in Cognitive Search. An "API key", which is described in this article, refers to a GUID used for authenticating a request. A "document key" refers to a unique string in your indexed content that's used to uniquely identify documents in a search index. API keys and document keys are unrelated.
+> A quick note about how "key" terminology is used in Cognitive Search. An "API key", which is described in this article, refers to a GUID used for authenticating a request. A separate term, "document key", refers to a unique string in your indexed content that's used to uniquely identify documents in a search index.
 
 ## Types of API keys