Merge pull request #1761 from MicrosoftDocs/main

11/28/2024 PM Publish

Author: Taojunshen

articles/search/search-get-started-rbac.md

@@ -7,14 +7,14 @@ ms.author: heidist
 ms.service: azure-ai-search
 
 ms.topic: quickstart
-ms.date: 11/26/2024
+ms.date: 11/28/2024
 ---
 
 # Quickstart: Connect without keys
 
-Configure Azure AI Search to use Microsoft Entra ID authentication and roles. Connect from your local system, running Jupyter notebooks, or using a REST client.
+Configure Azure AI Search to use Microsoft Entra ID authentication and role-based access control (RBAC). Connect from your local system using your personal identity, using Jupyter notebooks or a REST client to interact with your search service.
 
-If you stepped through other quickstarts that connect using API keys, this quickstart shows you how to switch to identity-based authentication so that you can avoid hard-coded API keys in your example code.
+If you stepped through other quickstarts that connect using API keys, this quickstart shows you how to switch to identity-based authentication so that you can avoid hard-coded keys in your example code.
 
 ## Prerequisites
 
@@ -24,43 +24,51 @@ If you stepped through other quickstarts that connect using API keys, this quick
 
 - A command line tool, such as the [Azure CLI](/cli/azure/install-azure-cli).
 
-## Step 1: Set up your Azure subscription and tenant
+## Step 1: Get your Azure subscription and tenant IDs
 
 This step is necessary if you have more than one subscription or tenant.
 
 1. Get the Azure subscription and tenant for your search service:
 
-   1. Sign into the Azure portal and navigate to your search service.
+   1. Sign into the [Azure portal](https://portal.azure.com) and navigate to your search service.
 
    1. Notice the subscription name and ID in **Overview** > **Essentials**.
 
-   1. Select the subscription name to view the parent management group (tenant ID).
+   1. Now select the subscription name to confirm the parent management group (tenant ID) on the next page.
 
       :::image type="content" source="media/search-get-started-rbac/select-subscription-name.png" lightbox="media/search-get-started-rbac/select-subscription-name.png" alt-text="Screenshot of the portal page providing the subscription name":::
 
-1. Identify the active Azure subscription and tenant on your local device:
+1. Switching to your local device and a command prompt, identify the active Azure subscription and tenant:
 
-   `az account show`
+   ```azurecli
+   az account show
+   ```
 
-1. Set your Azure subscription to the subscription and tenant:
+1. If the active subscription is different from the information obtained in the previous step, change the subscription ID. Next, sign in to Azure using the tenant ID also found in the previous step:
 
-   `az account set --subscription <your-subscription-id>`
+   ```azurecli
+    az account set --subscription <your-subscription-id>
 
-   `az login --tenant <your-tenant-id>`
+    az login --tenant <your-tenant-id>
+   ```
 
-1. Check your tenant ID:
+1. Verify your tenant ID:
 
-   `az account show --query tenantId --output tsv`
+   ```azurecli
+   az account show --query tenantId --output tsv
+   ```
 
-## Step 2: Configure Azure AI Search for Microsoft Entra ID authentication
+## Step 2: Configure Azure AI Search for RBAC
 
-1. Sign in to the Azure portal and navigate to your Azure AI Search service.
+1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to your Azure AI Search service.
 
 1. Enable role-based access control (RBAC):
 
    1. Go to **Settings** > **Keys**.
 
-   1. Choose **Role-based control** or **Both** if you need time to transition clients to role-based access control1.
+   1. Choose **Role-based control** or **Both** if you need time to transition clients to role-based access control.
+
+      If you choose **Role-based control**, make sure that you assign yourself *all* roles named in the next instruction or you won't be able to complete tasks in the portal or through a  local client.
 
 1. Assign roles in the Azure portal:
 
@@ -70,10 +78,23 @@ This step is necessary if you have more than one subscription or tenant.
 
    1. Select **+ Add** > **Add role assignment**.
 
-   1. Choose a role (Search Service Contributor, Search Index Data Contributor, Search Index Data Reader) and assign it to your Microsoft Entra user or group identity. These three roles provide the full set of permissions for creating, loading, and querying objects on Azure AI Search. For more information, see [Connect using roles](search-security-rbac.md).
+   1. Choose a role (Search Service Contributor, Search Index Data Contributor, Search Index Data Reader) and assign it to your Microsoft Entra user or group identity.
+
+      Repeat for each role.
+
+      You need all three roles for creating, loading, and querying objects on Azure AI Search. For more information, see [Connect using roles](search-security-rbac.md).
+
+> [!TIP]
+> Later, if you get authentication failure errors, recheck the settings in this section. There could be policies at the subscription or resource group level that override any API settings you specify.
 
 ## Step 3: Connect from your local system
 
+If you haven't yet signed in to Azure:
+
+```azurecli
+az login
+```
+
 ### Using Python and Jupyter notebooks
 
 1. Install the Azure Identity and Azure Search libraries:
@@ -105,7 +126,7 @@ Several quickstarts and tutorials use a REST client, such as Visual Studio Code
 
 1. Get a personal identity token:
 
-   `az account get-access-token --resource https://<your-search-service-name>.search.windows.net`
+   `az account get-access-token --scope https://search.azure.com/.default`
 
 1. Extract the token from the output: