crosslinks, intro clean up

Author: HeidiSteen

articles/search/TOC.yml

@@ -422,32 +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)
       href: search-security-rbac.md
     - name: Assign roles (apps)
       href: keyless-connections.md
-    - name: Authenticate using API keys
-      href: search-security-api-keys.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: 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
@@ -460,12 +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: 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-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: