Merge pull request #225144 from HeidiSteen/heidist-rbac

[azure search] RBAC doc fixes (removed preview sign up)

Author: v-shils

articles/search/search-api-preview.md

@@ -23,7 +23,7 @@ Preview features that transition to general availability are removed from this l
 |Feature                          | Category | Description | Availability  |
 |---------|------------------|-------------|---------------|
 |  [**Azure Files indexer**](search-file-storage-integration.md) | Indexer data source | Adds REST API support for creating indexers for [Azure Files](https://azure.microsoft.com/services/storage/files/) | Public preview, [Search REST API 2021-04-30-Preview](/rest/api/searchservice/index-preview). Announced in November 2021.  |
-| [**Azure RBAC support (data plane)**](search-security-rbac.md) | Security | Use new built-in roles to control access to indexes and indexing, eliminating or reducing the dependency on API keys. | Public preview ([registration required](./search-security-rbac.md?tabs=config-svc-portal%2croles-portal%2ctest-portal#step-1-preview-sign-up)). After you're registered, use the Azure portal or the Management REST API version 2021-04-01-Preview to configure a search service for data plane authentication. Announced in July 2021. |
+| [**Azure RBAC support (data plane)**](search-security-rbac.md) | Security | Use new built-in roles to control access to indexes and indexing, eliminating or reducing the dependency on API keys. | Public preview. Use the Azure portal or the Management REST API version 2021-04-01-Preview to configure a search service for data plane authentication. Announced in July 2021. |
 | [**Search REST API 2021-04-30-Preview**](/rest/api/searchservice/index-preview) | Security | Modifies [Create or Update Data Source](/rest/api/searchservice/preview-api/create-or-update-data-source) to support managed identities under Azure Active Directory, for indexers that connect to external data sources. | Public preview, [Search REST API 2021-04-30-Preview](/rest/api/searchservice/index-preview). Announced in May 2021.  |
 | [**Management REST API 2021-04-01-Preview**](/rest/api/searchmanagement/) | Security | Modifies [Create or Update Service](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update) to support new [DataPlaneAuthOptions](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update#dataplaneauthoptions). | Public preview, [Management REST API](/rest/api/searchmanagement/), API version 2021-04-01-Preview. Announced in May 2021. |
 | [**Reset Documents**](search-howto-run-reset-indexers.md) | Indexer | Reprocesses individually selected search documents in indexer workloads. | Use the [Reset Documents REST API](/rest/api/searchservice/preview-api/reset-documents), API versions 2021-04-30-Preview or 2020-06-30-Preview. |

articles/search/search-howto-aad.md

@@ -26,40 +26,67 @@ This article shows you how to configure your client for Azure AD:
 
 + Update your client code to call [DefaultAzureCredential()](/dotnet/api/azure.identity.defaultazurecredential)
 
-## Prepare your search service
+## Configure role-based access for data plane
 
-As a first step, sign up for the preview and enable role-based access control (RBAC) on your [search service](search-create-service-portal.md).
+**Applies to:** Search Index Data Contributor, Search Index Data Reader, Search Service Contributor
 
-### Sign up for the preview
+In this step, configure your search service to recognize an **authorization** header on data requests that provide an OAuth2 access token.
 
-RBAC for data plane operations is in preview. In this step, add the preview feature to your Azure subscription.
+### [**Azure portal**](#tab/config-svc-portal)
 
-1. Open [Azure portal](https://portal.azure.com/) and find your search service
+1. [Sign in to Azure portal](https://portal.azure.com) and open the search service page.
 
-1. On the left-nav pane, select **Keys**.
+1. Select **Keys** in the left navigation pane.
 
-1. In the blue banner that mentions the preview, select **Register** to add the feature to your subscription.
+   :::image type="content" source="media/search-create-service-portal/set-authentication-options.png" lightbox="media/search-create-service-portal/set-authentication-options.png" alt-text="Screenshot of the keys page with authentication options." border="true":::
 
-   :::image type="content" source="media/search-howto-aad/rbac-signup-portal.png" alt-text="Screenshot of how to sign up for the rbac preview in the portal" border="true" :::
+1. Choose an **API access control** option. We recommend **Both** if you want flexibility or need to migrate apps. 
 
-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).
+   | Option | Status | Description |
+   |--------|--------|-------------|
+   | API Key | Generally available (default) | Requires an [admin or query API keys](search-security-api-keys.md) on the request header for authorization. No roles are used. |
+   | Role-based access control | Preview | Requires membership in a role assignment to complete the task, described in the next step. It also requires an authorization header. |
+   | Both | Preview | Requests are valid using either an API key or role-based access control. |
 
-> [!NOTE]
-> Once you add the preview to your subscription, all search services in the subscription are 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 a later step.
+The change is effective immediately, but wait a few seconds before testing. 
+
+All network calls for search service operations and content will respect the option you select: API keys, bearer token, or either one if you select **Both**.
+
+When you enable role-based access control in the portal, the failure mode will be "http401WithBearerChallenge" if authorization fails.
+
+### [**REST API**](#tab/config-svc-rest)
+
+Use the Management REST API version 2021-04-01-Preview, [Create or Update Service](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update), to configure your service.
 
-### Enable RBAC for data plane operations
+All calls to the Management REST API are authenticated through Azure Active Directory, with Contributor or Owner permissions. For help setting up authenticated requests in Postman, see [Manage Azure Cognitive Search using REST](search-manage-rest.md).
 
-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. 
+1. Get service settings so that you can review the current configuration.
 
-1. Navigate to your search service in the [Azure portal](https://portal.azure.com/).
+   ```http
+   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2021-04-01-preview
+   ```
 
-1. On the left navigation pane, select **Keys**.
+1. Use PATCH to update service configuration. The following modifications enable both keys and role-based access. If you want a roles-only configuration, see [Disable API keys](search-security-rbac.md#disable-api-key-authentication).
 
-1. Choose whether to allow both key-based and role-based access control, or only role-based access control.
+   Under "properties", set ["authOptions"](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update#dataplaneauthoptions) to "aadOrApiKey". The "disableLocalAuth" property must be false to set "authOptions".
 
-   :::image type="content" source="media/search-howto-aad/portal-api-access-control.png" alt-text="Screenshot of authentication options for azure cognitive search in the portal" border="true" :::
+   Optionally, set ["aadAuthFailureMode"](/rest/api/searchmanagement/2021-04-01-preview/services/create-or-update#aadauthfailuremode) to specify whether 401 is returned instead of 403 when authentication fails. Valid values are "http401WithBearerChallenge" or "http403".
 
-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).
+    ```http
+    PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
+    {
+        "properties": {
+            "disableLocalAuth": false,
+            "authOptions": {
+                "aadOrApiKey": {
+                    "aadAuthFailureMode": "http401WithBearerChallenge"
+                }
+            }
+        }
+    }
+    ```
+
+---
 
 ## Create a managed identity
 
@@ -111,7 +138,7 @@ It's a best practice to grant minimum permissions. If your application only need
 
 You can assign multiple roles, such as Search Service Contributor and Search Index Data Contributor, if your application needs comprehensive access to the search services, objects, and content.
 
-You can also [assign roles using PowerShell](./search-security-rbac.md?tabs=config-svc-rest%2croles-powershell%2ctest-rest#step-3-assign-roles).
+You can also [assign roles using PowerShell](search-security-rbac.md#assign-roles).
 
 ## Set up Azure AD authentication in your client
 
@@ -124,15 +151,17 @@ Azure AD authentication is also supported in the preview SDKs for [Java](https:/
 
 ### [**.NET SDK**](#tab/aad-dotnet)
 
-The Azure SDKs make it easy to integrate with Azure AD. Version [11.4.0-beta.2](https://www.nuget.org/packages/Azure.Search.Documents/11.4.0-beta.2) and newer of the .NET SDK support Azure AD authentication.
+Use [Azure.Search.Documents version 11.4.0](https://www.nuget.org/packages/Azure.Search.Documents/11.4.0) for Azure AD authentication.
 
 The following instructions reference an existing C# sample to demonstrate the code changes.
 
 1. As a starting point, clone the [source code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/master/quickstart/v11) for the [C# quickstart](search-get-started-dotnet.md).
 
    The sample currently uses key-based authentication and the `AzureKeyCredential` to create the `SearchClient` and `SearchIndexClient` but you can make a small change to switch over to role-based authentication. 
 
-1. Next, import the [Azure.Identity](https://www.nuget.org/packages/Azure.Identity/) library to get access to other authentication techniques.
+1. Update the Azure.Search.Documents Nuget package to version 11.4 or later.
+
+1. Import the [Azure.Identity](https://www.nuget.org/packages/Azure.Identity/) library to get access to other authentication techniques.
 
 1. Instead of using `AzureKeyCredential` in the beginning of `Main()` in [Program.cs](https://github.com/Azure-Samples/azure-search-dotnet-samples/blob/master/quickstart/v11/AzureSearchQuickstart-v11/Program.cs), use `DefaultAzureCredential` like in the code snippet below: 
 

articles/search/search-manage-rest.md

@@ -1,5 +1,5 @@
 ---
-title: REST APIs for search management
+title: Manage with REST
 titleSuffix: Azure Cognitive Search
 description: Create and configure an Azure Cognitive Search service with the Management REST API. The Management REST API is comprehensive in scope, with access to generally available and preview features.
 
@@ -36,11 +36,11 @@ All of the Management REST APIs have examples. If a task isn't covered in this a
 
 ## Prerequisites
 
-* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-search/)
+* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-search/).
 
-* [Postman](https://www.postman.com/downloads/) or another REST client that sends HTTP requests
+* [Postman](https://www.postman.com/downloads/) or another REST client that sends HTTP requests.
 
-* [Azure CLI](/cli/azure/install-azure-cli) used to set up a security principle for the client
+* [Azure CLI](/cli/azure/install-azure-cli) used to set up a security principle for the client. You must have owner or administrator permissions to create  a security principle.
 
 ## Create a security principal
 
@@ -190,28 +190,25 @@ PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups
 
 <a name="enable-rbac"></a>
 
-## (preview) Enable Azure role-based authentication for data plane
+## (preview) Configure role-based access for data plane
 
-To use Azure role-based access control (Azure RBAC), set "authOptions" to "aadOrApiKey" and then send the request.
+**Applies to:** Search Index Data Contributor, Search Index Data Reader, Search Service Contributor
 
-If you want to use Azure RBAC exclusively, [turn off API key authentication](search-security-rbac.md#disable-api-key-authentication) by following up a second request, this time setting "disableLocalAuth" to "false".
+In this step, configure your search service to recognize an **authorization** header on data requests that provide an OAuth2 access token.
+
+To use Azure role-based access control (Azure RBAC) for data plane operations, set "authOptions" to "aadOrApiKey" and then send the request.
+
+If you want to use Azure RBAC exclusively, [turn off API key authentication](search-security-rbac.md#disable-api-key-authentication) by following up with a second request, this time setting "disableLocalAuth" to "true".
 
 ```rest
-PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
+PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
 {
-  "location": "{{region}}",
-  "tags": {
-    "app-name": "My e-commerce app"
-  },
-  "sku": {
-    "name": "standard"
-  },
   "properties": {
-    "replicaCount": 1,
-    "partitionCount": 1,
-    "hostingMode": "default",
     "disableLocalAuth": false,
-    "authOptions": "aadOrApiKey"
+    "authOptions": {
+      "aadOrApiKey": {
+        "aadAuthFailureMode": "http401WithBearerChallenge"
+      }
     }
   }
 }
@@ -226,16 +223,9 @@ If you're using [customer-managed encryption](search-security-manage-encryption-
 When you enable this policy, any REST calls that create objects containing sensitive data, such as the connection string within a data source, will fail if an encryption key isn't provided: `"Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."`
 
 ```rest
-PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
+PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
 {
-  "location": "westus",
-  "sku": {
-    "name": "standard"
-  },
   "properties": {
-    "replicaCount": 1,
-    "partitionCount": 1,
-    "hostingMode": "default",
     "encryptionWithCmk": {
       "enforcement": "Enabled",
       "encryptionComplianceStatus": "Compliant"
@@ -251,16 +241,12 @@ PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups
 Although [semantic search isn't enabled](semantic-search-overview.md#enable-semantic-search) by default, you could lock down the feature at the service level.
 
 ```rest
-PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
-    {
-      "location": "{{region}}",
-      "sku": {
-        "name": "standard"
-      },
-      "properties": {
-        "semanticSearch": "disabled"
-      }
-    }
+PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
+{
+  "properties": {
+    "semanticSearch": "disabled"
+  }
+}
 ```
 
 <a name="disable-external-access"></a>
@@ -270,16 +256,9 @@ PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups
 Azure Cognitive Search [writes to external data sources](search-indexer-securing-resources.md) when updating a knowledge store, saving debug session state, or caching enrichments. The following example disables these workloads at the service level.
 
 ```rest
-PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
+PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
 {
-  "location": "{{region}}",
-  "sku": {
-    "name": "standard"
-  },
   "properties": {
-    "replicaCount": 1,
-    "partitionCount": 1,
-    "hostingMode": "default",
     "disabledDataExfiltrationOptions": [
       "All"
     ]