Updated RBAC quickstart

haileytap · haileytap · commit ef1aecb8e164 · 2025-07-09T11:32:48.000-04:00
diff --git a/articles/search/includes/quickstarts/full-text-rest.md b/articles/search/includes/quickstarts/full-text-rest.md
@@ -89,11 +89,11 @@ To set up your request file:
     @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
 
     ### List existing indexes by name
-        GET {{baseUrl}}/indexes?api-version=2024-07-01
+    GET {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
         Authorization: Bearer {{token}}
     ```
 
-1. Replace the `@baseUrl` and `@token` placeholders with the values you obtained in [Get endpoint and token](#get-endpoint-and-token).
+1. Replace the `@baseUrl` and `@token` placeholders with the values you obtained in [Get endpoint and token](#get-endpoint-and-token). Don't include quotation marks.
 
 1. Under `### List existing indexes by name`, select **Send Request**.
 
diff --git a/articles/search/includes/quickstarts/search-get-started-rbac-python.md b/articles/search/includes/quickstarts/search-get-started-rbac-python.md
@@ -4,12 +4,12 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 07/08/2025
+ms.date: 07/09/2025
 ---
 
-In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to connect to Azure AI Search from your local system. You then use Python in Visual Studio Code to interact with your search service.
+In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to establish a keyless connection to your Azure AI Search service. You then use Python in Visual Studio Code to interact with the service.
 
-We recommend keyless connections for granular permissions and identity-based authentication, which eliminate the need for hard-coded API keys in your code. However, if you prefer key-based connections, see [Connect to Azure AI Search using keys](../../search-security-api-keys.md).
+Keyless connections provide enhanced security through granular permissions and identity-based authentication. We don't recommend hard-coded API keys, but if you prefer them, see [Connect to Azure AI Search using keys](../../search-security-api-keys.md).
 
 <!-- This quickstart is a prerequisite for other quickstarts that use Microsoft Entra ID with role assignments. -->
 
@@ -25,25 +25,30 @@ We recommend keyless connections for granular permissions and identity-based aut
 
 [!INCLUDE [Setup](./search-get-started-rbac-setup.md)]
 
-## Set up authentication
+## Sign in to Azure
 
-Before you establish a keyless connection to your Azure AI Search service, you must use the Azure CLI to authenticate your identity with Microsoft Entra ID.
+Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains the service. This step establishes your Microsoft Entra identity, which `DefaultAzureCredential` uses to authenticate requests in the next section.
 
-To set up authentication:
+To sign in:
 
 1. On your local system, open a command-line tool.
 
-1. Sign in to the subscription whose ID you obtained in [Get service information](#get-service-information).
+1. Sign in to Azure.
 
    ```azurecli
    az login
    ```
 
+1. (Conditional) If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+
 ## Connect to Azure AI Search
 
-You can use the Python extension and Jupyter package to send requests to your Azure AI Search service. For request authentication, use the `DefaultAzureCredential` class from the Azure Identity library.
+> [!NOTE]
+> This section illustrates the basic Python pattern for keyless connections. For comprehensive guidance, see a specific quickstart or tutorial, such as [Quickstart: Run agentic retrieval in Azure AI Search](../../search-quickstart-agentic-retrieval.md).
+
+You can use Python notebooks in Visual Studio Code to send requests to your Azure AI Search service. For request authentication, use the `DefaultAzureCredential` class from the Azure Identity library.
 
-To use Python for keyless connections:
+To connect using Python:
 
 1. On your local system, open Visual Studio Code.
 
@@ -55,27 +60,38 @@ To use Python for keyless connections:
    pip install azure-identity azure-search-documents
    ```
 
-1. Create another code cell to authenticate with `DefaultAzureCredential` and connect to your search service.
+1. Create another code cell to authenticate and connect to your search service.
 
    ```python
    from azure.identity import DefaultAzureCredential
-   from azure.search.documents import SearchClient
+   from azure.search.documents.indexes import SearchIndexClient
     
    service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
-   index_name = "hotels-sample-index"
-    
    credential = DefaultAzureCredential()
-   client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)
+   client = SearchIndexClient(endpoint=service_endpoint, credential=credential)
     
-   results = client.search("beach access")
-   for result in results:
-      print(result)
+   # List existing indexes
+   indexes = client.list_indexes()
+    
+   for index in indexes:
+      index_dict = index.as_dict()
+      print(json.dumps(index_dict, indent=2))
    ```
 
+1. Set `service_endpoint` to the value you obtained in [Get service information](#get-service-information).
+
+1. Select **Run All** to run both code cells.
+
+   The output should list existing indexes on your search service, indicating a successful connection.
+
 ### Troubleshoot 401 errors
 
+If you encounter a 401 error, follow these troubleshooting steps:
+
 + Revisit [Configure role-based access](#configure-role-based-access). Your search service must have **Role-based access control** or **Both** enabled. Policies at the subscription or resource group level might also override your role assignments.
 
-+ Revisit [Set up authentication](#set-up-authentication). You must sign in to the correct subscription for your search service.
++ Revisit [Sign in to Azure](#sign-in-to-azure). You must sign in to the subscription that contains your search service.
+
++ Make sure your endpoint variable has surrounding quotes.
 
-If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with [Set up authentication](#set-up-authentication).
++ If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with [Sign in to Azure](#sign-in-to-azure).
diff --git a/articles/search/includes/quickstarts/search-get-started-rbac-rest.md b/articles/search/includes/quickstarts/search-get-started-rbac-rest.md
@@ -4,12 +4,12 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 07/08/2025
+ms.date: 07/09/2025
 ---
 
-In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to connect to Azure AI Search from your local system. You then use REST in Visual Studio Code to interact with your search service.
+In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to establish a keyless connection to your Azure AI Search service. You then use REST in Visual Studio Code to interact with the service.
 
-We recommend keyless connections for granular permissions and identity-based authentication, which eliminate the need for hard-coded API keys in your code. However, if you prefer key-based connections, see [Connect to Azure AI Search using keys](../../search-security-api-keys.md).
+Keyless connections provide enhanced security through granular permissions and identity-based authentication. We don't recommend hard-coded API keys, but if you prefer them, see [Connect to Azure AI Search using keys](../../search-security-api-keys.md).
 
 <!-- This quickstart is a prerequisite for other quickstarts that use Microsoft Entra ID with role assignments. -->
 
@@ -25,73 +25,73 @@ We recommend keyless connections for granular permissions and identity-based aut
 
 [!INCLUDE [Setup](./search-get-started-rbac-setup.md)]
 
-## Set up authentication
+## Get token
 
-Before you establish a keyless connection to your Azure AI Search service, you must use the Azure CLI to authenticate your identity and generate a Microsoft Entra ID token. You specify this token in the next section.
+Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains the service and generate a Microsoft Entra ID token. You use this token to authenticate requests in the next section.
 
-To set up authentication:
+To get your token:
 
 1. On your local system, open a command-line tool.
 
-1. Sign in to the subscription whose ID you obtained in [Get service information](#get-service-information).
+1. Sign in to Azure.
 
    ```azurecli
    az login
    ```
 
+1. (Conditional) If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+
 1. Generate an access token.
 
-    ```azurecli
-    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
-    ```
+   ```azurecli
+   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
+   ```
 
-1. Make a note of the token.
+1. Make a note of the token output.
 
 ## Connect to Azure AI Search
 
-You can use the REST Client extension to send requests to Azure AI Search. For request authentication, include an `Authorization` header with the Microsoft Entra ID token you previously generated.
+> [!NOTE]
+> This section illustrates the basic REST pattern for keyless connections. For comprehensive guidance, see a specific quickstart or tutorial, such as [Quickstart: Run agentic retrieval in Azure AI Search](../../search-quickstart-agentic-retrieval.md).
 
-To use REST for keyless connections:
+You can use the REST Client extension in Visual Studio Code to send requests to your Azure AI Search service. For request authentication, include an `Authorization` header with the Microsoft Entra ID token you previously generated.
+
+To connect using REST:
 
 1. On your local system, open Visual Studio Code.
 
 1. Create a `.rest` or `.http` file.
 
-1. Paste the following placeholders into the file.
+1. Paste the following placeholders and request into the file.
 
    ```http
    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
    @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
+
+   ### List existing indexes
+   GET {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
+      Content-Type: application/json
+      Authorization: Bearer {{token}}
    ```
 
 1. Replace `@baseUrl` with the value you obtained in [Get service information](#get-service-information).
 
-1. Replace `@token` with the value you obtained in [Set up authentication](#set-up-authentication).
+1. Replace `@token` with the value you obtained in [Get token](#get-token).
 
-1. Make a REST call to authenticate with your token and connect to your search service.
+1. Under `### List existing indexes`, select **Send Request**.
 
-   ```http
-   POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
-      Content-type: application/json
-      Authorization: Bearer {{token}}
-    
-      {
-         "queryType": "simple",
-         "search": "beach access",
-         "filter": "",
-         "select": "HotelName,Description,Category,Tags",
-         "count": true
-      }
-   ```
+   You should receive an `HTTP/1.1 200 OK` response, indicating a successful connection to your search service.
 
 ### Troubleshoot 401 errors
 
+If you encounter a 401 error, follow these troubleshooting steps:
+
 + Revisit [Configure role-based access](#configure-role-based-access). Your search service must have **Role-based access control** or **Both** enabled. Policies at the subscription or resource group level might also override your role assignments.
 
-+ Revisit [Set up authentication](#set-up-authentication). You must sign in to the correct subscription for your search service.
++ Revisit [Get token](#get-token). You must sign in to the subscription that contains your search service.
 
 + Make sure your endpoint and token variables don't have surrounding quotes or extra spaces.
 
 + Make sure your token doesn't have the `@` symbol in the request header. For example, if the variable is `@token`, the reference in the request should be `{{token}}`.
 
-If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with [Set up authentication](#set-up-authentication).
++ If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with [Get token](#get-token).
diff --git a/articles/search/includes/quickstarts/search-get-started-rbac-setup.md b/articles/search/includes/quickstarts/search-get-started-rbac-setup.md
@@ -19,17 +19,21 @@ To configure access:
 
 1. Select **Role-based access control** or **Both** if you need time to transition clients to RBAC.
 
+   :::image type="content" source="../../media/search-get-started-rbac/access-control-options.png" lightbox="../../media/search-get-started-rbac/access-control-options.png" alt-text="Screenshot of the access control options in the Azure portal.":::
+
 1. From the left pane, select **Access control (IAM)**.
 
 1. Select **Add** > **Add role assignment**.
 
+   :::image type="content" source="../../media/search-get-started-rbac/add-role-assignment.png" lightbox="../../media/search-get-started-rbac/add-role-assignment.png" alt-text="Screenshot of the dropdown menu for adding a role assignment in the Azure portal.":::
+
 1. Assign the **Search Service Contributor** role to your user account or managed identity.
 
 1. Repeat the role assignment for **Search Index Data Contributor**.
 
 ## Get service information
 
-In this section, you retrieve the subscription ID and endpoint of your Azure AI Search service. You use these values for authentication and connection in the following sections.
+In this section, you retrieve the subscription ID and endpoint of your Azure AI Search service. If you have one subscription, skip the subscription ID and only retrieve the endpoint. You use these values in the remaining sections of this quickstart.
 
 To get your service information:
 
diff --git a/articles/search/media/search-get-started-rbac/access-control-options.png b/articles/search/media/search-get-started-rbac/access-control-options.png
diff --git a/articles/search/media/search-get-started-rbac/add-role-assignment.png b/articles/search/media/search-get-started-rbac/add-role-assignment.png
diff --git a/articles/search/search-get-started-rbac.md b/articles/search/search-get-started-rbac.md
@@ -26,8 +26,6 @@ zone_pivot_groups: search-get-started-rbac
 
 ## Related content
 
-+ [Configure a system- or user-assigned managed identity](search-howto-managed-identities-data-sources.md) for your search service.
-
-+ [Use role assignments](keyless-connections.md) to authorize access to other Azure resources.
-
-+ [Set inbound rules](service-configure-firewall.md) to accept or reject Azure AI Search requests based on IP address.
++ [Configure a managed identity in Azure AI Search](search-howto-managed-identities-data-sources.md)
++ [Connect your app to Azure AI Search using identities](keyless-connections.md)
++ [Configure network access and firewall rules for Azure AI Search](service-configure-firewall.md)
