Merge pull request #279587 from HeidiSteen/heidist-june28

[azure search] Security TOC updates

Author: v-dirichards

articles/search/TOC.yml

@@ -422,26 +422,18 @@
     items:
     - name: Configure network access
       href: service-configure-firewall.md
+    - name: Authenticate with keys
+      href: search-security-api-keys.md
     - name: Enable role-based access
       href: search-security-enable-roles.md
-    - name: Assign roles (users and groups)
+    - name: Assign roles (users)
       href: search-security-rbac.md
-    - name: Inbound connections
-      items:
-      - name: Connect using API keys
-        href: search-security-api-keys.md
-      - name: Code without keys
-        href: keyless-connections.md
-      - name: Create a private endpoint
-        href: service-create-private-endpoint.md
-      - name: Troubleshoot private connections
-        href: troubleshoot-shared-private-link-resources.md
+    - name: Assign roles (apps)
+      href: keyless-connections.md
     - name: Outbound connections
       items:
       - name: Configure a managed identity
         href: search-howto-managed-identities-data-sources.md
-      - name: Connect as a trusted service
-        href: search-indexer-howto-access-trusted-service-exception.md
       - name: Connect using a managed identity
         items:
         - name: Azure Storage
@@ -454,18 +446,26 @@
           href: search-index-azure-sql-managed-instance-with-managed-identity.md
       - name: Connect through a firewall
         href: search-indexer-howto-access-ip-restricted.md
+      - name: Connect as a trusted service
+        href: search-indexer-howto-access-trusted-service-exception.md
       - name: Connect through a shared private link
         href: search-indexer-howto-access-private.md
       - name: Connect to a SQL managed instance private endpoint
         href: search-indexer-how-to-access-private-sql.md
-    - name: Data encryption
-      items:
-      - name: Customer-managed keys
-        href: search-security-manage-encryption-keys.md
-      - name: Find encrypted objects
-        href: search-security-get-encryption-keys.md
     - name: Document-level security
       href: search-security-trimming-for-azure-search.md
+    - name: Advanced options
+      items:
+      - name: Create a private endpoint
+        href: service-create-private-endpoint.md
+      - name: Troubleshoot private connections
+        href: troubleshoot-shared-private-link-resources.md
+      - name: Data encryption
+        items:
+        - name: Customer-managed keys
+          href: search-security-manage-encryption-keys.md
+        - name: Find encrypted objects
+          href: search-security-get-encryption-keys.md
   - name: Development
     items:
     - name: API versions

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

@@ -10,17 +10,14 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 04/22/2024
+ms.date: 06/28/2024
 ---
 
 # Connect to Azure AI Search using key authentication
 
 Azure AI 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 is accepted if both the request and the API key are valid.
 
-Key-based authentication is the default. You can disable it if you opt in for role-based authentication.
-
-> [!NOTE]
-> A quick note about *key* terminology. An *API key* is a GUID used for authentication. A separate term, *document key* is a unique string in your indexed content that uniquely identifies documents in a search index.
+Key-based authentication is the default. You can disable it if you opt in for [role-based authentication](search-security-enable-roles.md).
 
 ## Types of API keys
 

articles/search/search-security-enable-roles.md

@@ -16,7 +16,7 @@ ms.date: 06/18/2024
 
 If you want to use Azure role assignments for authorized access to Azure AI Search, this article explains how to enable role-based access for your search service.
 
-Role-based access for data plane operations is optional, but recommended. The alternative is [key-based authentication](search-security-api-keys.md), which is the default. 
+Role-based access for data plane operations is optional, but recommended as the more secure option. The alternative is [key-based authentication](search-security-api-keys.md), which is the default. 
 
 Roles for service administration (control plane) are built in and can't be enabled or disabled. 
 

articles/search/search-security-overview.md

@@ -10,7 +10,7 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 05/28/2024
+ms.date: 06/28/2024
 ---
 
 # Security overview for Azure AI Search
@@ -23,7 +23,7 @@ An Azure AI Search service is hosted on Azure and is typically accessed by clien
 
 Azure AI Search has three basic network traffic patterns:
 
-+ Inbound requests made by a client to the search service (the predominant pattern)
++ Inbound requests made by a user or client to the search service (the predominant pattern)
 + Outbound requests issued by the search service to other services on Azure and elsewhere
 + Internal service-to-service requests over the secure Microsoft backbone network
 
@@ -52,12 +52,12 @@ Internal requests are secured and managed by Microsoft. You can't configure or c
 Internal traffic consists of:
 
 + Service-to-service calls for tasks like authentication and authorization through Microsoft Entra ID, resource logging sent to Azure Monitor, and [private endpoint connections](service-create-private-endpoint.md) that utilize Azure Private Link.
-+ Requests made to Azure AI services APIs for [built-in skills](cognitive-search-predefined-skills.md).
++ Requests made to Azure AI services APIs for [built-in skills](cognitive-search-predefined-skills.md)
 + Requests made to the machine learning models that support [semantic ranking](semantic-search-overview.md#availability-and-pricing).
 
 ### Outbound traffic
 
-Outbound requests can be secured and managed by you. Outbound requests originate from a search service to other applications. These requests are typically made by indexers for text-based indexing, skills-based AI enrichment, and vectorizations at query time. Outbound requests include both read and write operations.
+Outbound requests can be secured and managed by you. Outbound requests originate from a search service to other applications. These requests are typically made by indexers for text-based indexing, custom skills-based AI enrichment, and vectorizations at query time. Outbound requests include both read and write operations.
 
 The following list is a full enumeration of the outbound requests for which you can configure secure connections. A search service makes requests on its own behalf, and on the behalf of an indexer or custom skill.
 

articles/search/search-security-rbac.md

@@ -180,9 +180,11 @@ New-AzRoleAssignment -SignInName <email> `
 
 ### Assign roles for read-only queries
 
-Use the Search Index Data Reader role for apps and processes that only need read-access to an index. This is a very specific role. It grants [GET or POST access](/rest/api/searchservice/documents) to the *documents collection of a search index* for search, autocomplete, and suggestions.
+Use the Search Index Data Reader role for apps and processes that only need read-access to an index. 
 
-It doesn't support GET or LIST operations on an index or other top-level objects, or GET service statistics.
+This is a very specific role. It grants [GET or POST access](/rest/api/searchservice/documents) to the *documents collection of a search index* for search, autocomplete, and suggestions. It doesn't support GET or LIST operations on an index or other top-level objects, or GET service statistics.
+
+This section provides basic steps for setting up the role assignment and is here for completeness, but we recommend [Use Azure AI Search without keys ](keyless-connections.md) for comprehensive instructions on configuring your app for role-based access.
 
 #### [**Azure portal**](#tab/roles-portal-query)
 

articles/search/service-configure-firewall.md

@@ -15,7 +15,7 @@ ms.date: 06/27/2024
 
 # Configure network access and firewall rules for Azure AI Search
 
-By default, Azure AI Search is configured to allow connections over a public endpoint. Access to a search service *through* the public endpoint is protected by authentication and authorization protocols, but the endpoint itself is open to the internet at the network layer.
+By default, Azure AI Search is configured to allow connections over a public endpoint. Access to a search service *through* the public endpoint is protected by authentication and authorization protocols, but the endpoint itself is open to the internet at the network layer for data plane requests.
 
 If you aren't hosting a public web site, you might want to configure network access to automatically refuse requests unless they originate from an approved set of devices and cloud services. There are two mechanisms: