Merge pull request #5928 from haileytap/quickstarts

[Azure Search] Update search-get-started-rbac.md

Author: denrea

articles/search/includes/quickstarts/full-text-rest.md

@@ -89,7 +89,7 @@ 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}}
     ```
 

articles/search/includes/quickstarts/search-get-started-rbac-python.md

@@ -0,0 +1,95 @@
+---
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: include
+ms.date: 07/09/2025
+---
+
+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 your service.
+
+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. -->
+
+## Prerequisites
+
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
++ An [Azure AI Search service](../../search-create-service-portal.md) in any region or tier.
+
++ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
+
++ [Visual Studio Code](https://code.visualstudio.com/) with the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) and [Jupyter package](https://jupyter.org/install).
+
+[!INCLUDE [Setup](./search-get-started-rbac-setup.md)]
+
+## Sign in to Azure
+
+Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service. This step establishes your Microsoft Entra identity, which `DefaultAzureCredential` uses to authenticate requests in the next section.
+
+To sign in:
+
+1. On your local system, open a command-line tool.
+
+1. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+
+   ```azurecli
+   az login
+   ```
+
+## Connect to Azure AI Search
+
+> [!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-get-started-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 connect using Python:
+
+1. On your local system, open Visual Studio Code.
+
+1. Create a `.ipynb` file.
+
+1. Create a code cell to install the `azure-identity` and `azure-search-documents` libraries.
+
+   ```python
+   pip install azure-identity azure-search-documents
+   ```
+
+1. Create another code cell to authenticate and connect to your search service.
+
+   ```python
+   from azure.identity import DefaultAzureCredential
+   from azure.search.documents.indexes import SearchIndexClient
+    
+   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
+   credential = DefaultAzureCredential()
+   client = SearchIndexClient(endpoint=service_endpoint, credential=credential)
+    
+   # 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 the existing indexes (if any) 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 [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 [Sign in to Azure](#sign-in-to-azure).

articles/search/includes/quickstarts/search-get-started-rbac-rest.md

@@ -0,0 +1,95 @@
+---
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: include
+ms.date: 07/09/2025
+---
+
+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 your service.
+
+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. -->
+
+## Prerequisites
+
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
++ An [Azure AI Search service](../../search-create-service-portal.md) in any region or tier.
+
++ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
+
++ [Visual Studio Code](https://code.visualstudio.com/) with the [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).
+
+[!INCLUDE [Setup](./search-get-started-rbac-setup.md)]
+
+## Get token
+
+Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service and generate a Microsoft Entra ID token. You use this token to authenticate requests in the next section.
+
+To get your token:
+
+1. On your local system, open a command-line tool.
+
+1. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+
+   ```azurecli
+   az login
+   ```
+
+1. Generate an access token.
+
+   ```azurecli
+   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
+   ```
+
+1. Make a note of the token output.
+
+## Connect to Azure AI Search
+
+> [!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-get-started-agentic-retrieval.md).
+
+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 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 [Get token](#get-token).
+
+1. Under `### List existing indexes`, select **Send Request**.
+
+   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 [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 [Get token](#get-token).

articles/search/includes/quickstarts/search-get-started-rbac-setup.md

@@ -0,0 +1,46 @@
+---
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: include
+ms.date: 07/08/2025
+---
+
+## Configure role-based access
+
+In this section, you enable RBAC on your Azure AI Search service and assign the necessary roles for creating, loading, and querying search objects. For more information about these steps, see [Connect to Azure AI Search using roles](../../search-security-rbac.md).
+
+To configure access:
+
+1. Sign in to the [Azure portal](https://portal.azure.com) and select your search service.
+
+1. From the left pane, select **Settings > Keys**.
+
+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. If you only 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:
+
+1. Sign in to the [Azure portal](https://portal.azure.com) and select your search service.
+
+1. From the left pane, select **Overview**.
+
+1. Make a note of the subscription ID and endpoint.
+
+   :::image type="content" source="../../media/search-get-started-rbac/subscription-and-endpoint.png" lightbox="../../media/search-get-started-rbac/subscription-and-endpoint.png" alt-text="Screenshot of the subscription ID and endpoint in the Azure portal.":::