Merge pull request #179799 from dereklegenzoff/rbac-updates

updating rbac docs

Author: ShannonLeavitt

articles/search/media/search-howto-aad/portal-api-access-control.png

@@ -13,7 +13,7 @@ ms.date: 10/04/2021
 # Authorize search requests using Azure AD (preview)
 
 > [!IMPORTANT]
-> Role-based access control for data plane operations such as creating an index or querying an index is currently in public preview and available under [supplemental terms of use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). This functionality is only available in public clouds and may impact the latency of your operations while the functionality is in preview. 
+> Role-based access control for data plane operations, such as creating an index or querying an index, is currently in public preview and available under [supplemental terms of use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). This functionality is only available in public cloud regions and may impact the latency of your operations while the functionality is in preview.
 
 With Azure Active Directory (Azure AD), you can use role-based access control (RBAC) to grant access to your Azure Cognitive Search services. A key advantage of using Azure AD is that your credentials no longer need to be stored in your code. Azure AD authenticates the security principal (a user, group, or service principal) running the application. If authentication succeeds, Azure AD returns the access token to the application, and the application can then use the access token to authorize requests to Azure Cognitive Search. To learn more about the advantages of using Azure AD in your applications, see [Integrating with Azure Active Directory](../active-directory/develop/active-directory-how-to-integrate.md#benefits-of-integration).
 
@@ -29,28 +29,28 @@ The parts of Azure Cognitive Search's RBAC capabilities required to use Azure AD
 
 To add your subscription to the preview:
 
-1. Navigate to the **Subscriptions** page in the [Azure portal](https://portal.azure.com/).
-1. Select the subscription you want to use.
-1. On the left-hand side of the subscription page, select **Preview Features**.
-1. Use the search bar or filters to find and select **Role Based Access Control for Search Service (Preview)**
-1. Select **Register** to add the feature to your subscription.
+1. Navigate to your search service in the [Azure portal](https://portal.azure.com/).
+1. On the left-hand side of the page, select **Keys**.
+1. In the blue banner that mentions the preview, select **Register** to add the feature to your subscription.
 
-![sign up for rbac on afec](media/search-howto-aad/rbac-signup-afec.png)
+![screenshot of how to sign up for the rbac preview in the portal](media/search-howto-aad/rbac-signup-portal.png)
 
-For more information on adding preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md?tabs=azure-portal).
+You can also sign up for the preview using Azure Feature Exposure Control (AFEC) and searching for *Role Based Access Control for Search Service (Preview)*. For more information on adding preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md?tabs=azure-portal).
 
+> [!NOTE]
+> Once you add the preview to your subscription, all services in the subscription will be permanently enrolled in the preview. If you don't want RBAC on a given service, you can disable RBAC for data plane operations as shown in the next step.
 
 ### Enable RBAC for data plane operations
 
-Once your subscription is onboarded to the preview, you'll still need to enable RBAC for data plane operations so that you can use Azure AD authentication. By default, Azure Cognitive Search uses key-based authentication for data plane operations but you can change the setting to allow role-based access control. 
+Once your subscription is added to the preview, you'll still need to enable RBAC for data plane operations so that you can use Azure AD authentication. By default, Azure Cognitive Search uses key-based authentication for data plane operations but you can change the setting to allow role-based access control. 
 
 To enable role-based access control:
 
-1. Navigate to the Azure portal with this preview link: [https://ms.portal.azure.com/?feature.enableRbac=true](https://ms.portal.azure.com/?feature.enableRbac=true). 
+1. Navigate to your search service in the [Azure portal](https://portal.azure.com/).
 1. On the left navigation pane, select **Keys**.
 1. Determine if you'd like to allow both key-based and role-based access control, or only role-based access control.
 
-![authentication options for azure cognitive search in the portal](media/search-howto-aad/portal-api-access-control.png)
+![screenshot of authentication options for azure cognitive search in the portal](media/search-howto-aad/portal-api-access-control.png)
 
 You can also change these settings programatically as described in the [Azure Cognitive Search RBAC Documentation](./search-security-rbac.md?tabs=config-svc-rest%2croles-powershell%2ctest-rest#step-2-preview-configuration).
 
@@ -66,20 +66,20 @@ To register an application with Azure AD:
 1. Select **New Registration**.
 1. Give your application a name and select a supported account type, which determines who can use the application. Then, select **Register**.
 
-![Register an application wizard](media/search-howto-aad/register-app.png)
+![screenshot of the register an application wizard](media/search-howto-aad/register-app.png)
 
 At this point, you've created your Azure AD application and service principal. Make a note of tenant (or directory) ID and the client (or application) ID on the overview page of your app registration. You'll need those values in a future step.
 
 ## Create a client secret
 
 The application will also need a client secret or certificate to prove its identity when requesting a token. In this document, we'll show how to use a client secret.
 
-1. Navigate to the app registration you just created.
+1. Navigate to the app registration you created.
 1. Select **Certificates and secrets**.
-1. Under **Client secrets**, click **New client secret**.
+1. Under **Client secrets**, select **New client secret**.
 1. Provide a description of the secret and select the desired expiration interval.
 
-![create a client secret wizard](media/search-howto-aad/create-secret.png)
+![screenshot of create a client secret wizard](media/search-howto-aad/create-secret.png)
 
 Make sure to save the value of the secret in a secure location as you won't be able to access the value again. 
 
@@ -94,11 +94,11 @@ To assign a role to your app registration:
 1. Open the Azure portal and navigate to your search service.
 1. Select **Access Control (IAM)** in the left navigation pane.
 1. On the right side under **Grant access to this resource**, select **Add role assignment**.
-1. Select the role you'd like to use and then click **Next**.
-1. On the next page, click **Select members** and find the application you created previously. 
-1. Finally, click **Review + assign**.
+1. Select the role you'd like to use and then select **Next**.
+1. On the next page, select **Select members** and find the application you created previously. 
+1. Finally, select **Review + assign**.
 
-![Add role assignment in the azure portal](media/search-howto-aad/role-assignment.png)
+![screenshot of how to add role assignment in the azure portal](media/search-howto-aad/role-assignment.png)
 
 You can also [assign roles using PowerShell](./search-security-rbac.md?tabs=config-svc-rest%2croles-powershell%2ctest-rest#step-3-assign-roles).
 

articles/search/media/search-howto-aad/rbac-signup-afec.png

@@ -60,16 +60,16 @@ New built-in preview roles provide a granular set of permissions over content on
 
 To add your subscription to the preview:
 
-1. Navigate to the **Subscriptions** page in the [Azure portal](https://portal.azure.com/).
-1. Select the subscription you want to use.
-1. On the left-hand side of the subscription page, select **Preview Features**.
-1. Use the search bar or filters to find and select **Role Based Access Control for Search Service (Preview)**
-1. Select **Register** to add the feature to your subscription.
+1. Navigate to your search service in the [Azure portal](https://portal.azure.com/).
+1. On the left-hand side of the page, select **Keys**.
+1. In the blue banner that mentions the preview, select **Register** to add the feature to your subscription.
 
-![sign up for rbac on afec](media/search-howto-aad/rbac-signup-afec.png)
+![screenshot of how to sign up for the rbac preview in the portal](media/search-howto-aad/rbac-signup-portal.png)
 
-For more information on adding preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md?tabs=azure-portal).
+You can also sign up for the preview using Azure Feature Exposure Control (AFEC) and searching for *Role Based Access Control for Search Service (Preview)*. For more information on adding preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md?tabs=azure-portal).
 
+> [!NOTE]
+> Once you add the preview to your subscription, all services in the subscription will be permanently enrolled in the preview. If you don't want RBAC on a given service, you can disable RBAC for data plane operations as shown in the next step.
 
 ## Step 2: Preview configuration
 
@@ -81,7 +81,7 @@ In this step, configure your search service to recognize an **authorization** he
 
 ### [**Azure portal**](#tab/config-svc-portal)
 
-1. Open the portal with this syntax: [https://ms.portal.azure.com/?feature.enableRbac=true](https://ms.portal.azure.com/?feature.enableRbac=true).
+1. Open the [Azure portal](https://ms.portal.azure.com).
 
 1. Navigate to your search service.
 
@@ -144,10 +144,7 @@ You must be an **Owner** or have [Microsoft.Authorization/roleAssignments/write]
 
 ### [**Azure portal**](#tab/roles-portal)
 
-1. For preview roles, open the portal with this syntax: [https://ms.portal.azure.com/?feature.enableRbac=true](https://ms.portal.azure.com/?feature.enableRbac=true). You should see `feature.enableRbac=true` in the URL.
-
-   > [!NOTE]
-   > For users and groups assigned to a preview role, portal content such as indexes and indexers will only be visible if you open the portal with the feature flag. 
+1. Open the [Azure portal](https://ms.portal.azure.com).
 
 1. Navigate to your search service.
 
@@ -200,10 +197,7 @@ Recall that you can only scope access to top-level resources, such as indexes, s
 
 ### [**Azure portal**](#tab/test-portal)
 
-1. For preview roles, open the portal with this syntax: [https://ms.portal.azure.com/?feature.enableRbac=true](https://ms.portal.azure.com/?feature.enableRbac=true). 
-
-   > [!NOTE]
-   > For users and groups assigned to a preview role, portal content such as indexes and indexers will only be visible if you open the portal with the feature flag. 
+1. Open the [Azure portal](https://ms.portal.azure.com).
 
 1. Navigate to your search service.
 
@@ -310,4 +304,4 @@ To enable a Conditional Access policy for Azure Cognitive Search, follow the bel
 1. Save the policy.
 
 > [!IMPORTANT]
-> If your search service has a managed identity assigned to it, the specific search service will show up as a cloud app that can be included or excluded as part of the Conditional Access policy. Conditional Access policies cannot be enforced on a specific search service. Instead make sure you select the general **Azure Cognitive Search** cloud app.
+> If your search service has a managed identity assigned to it, the specific search service will show up as a cloud app that can be included or excluded as part of the Conditional Access policy. Conditional Access policies cannot be enforced on a specific search service. Instead make sure you select the general **Azure Cognitive Search** cloud app.