Merge pull request #223384 from HeidiSteen/heidist-rbac

[azure search] Prepare for RBAC GA

Author: denrea

articles/search/TOC.yml

@@ -214,19 +214,13 @@
       href: search-howto-move-across-regions.md
   - name: Security
     items:
-    - name: Data encryption
-      items:
-      - name: Customer-managed keys
-        href: search-security-manage-encryption-keys.md
-      - name: Find encrypted objects
-        href: search-security-get-encryption-keys.md
     - name: Inbound connections
       items:
-      - name: Use key authentication
+      - name: Connect using API keys
         href: search-security-api-keys.md
-      - name: Use Azure roles
+      - name: Connect using Azure roles
         href: search-security-rbac.md
-      - name: Authenticate apps with Azure AD
+      - name: Configure apps for Azure AD
         href: search-howto-aad.md
       - name: Configure an IP firewall
         href: service-configure-firewall.md
@@ -244,6 +238,12 @@
         href: search-indexer-howto-access-ip-restricted.md
       - name: Connect through private endpoints
         href: search-indexer-howto-access-private.md
+    - name: Data encryption
+      items:
+      - name: Customer-managed keys
+        href: search-security-manage-encryption-keys.md
+      - name: Find encrypted objects
+        href: search-security-get-encryption-keys.md
     - name: Document-level security
       items:
       - name: Security filters

articles/search/media/search-manage/azure-search-view-keys.png

@@ -30,13 +30,13 @@ This article demonstrates how to create the application step by step. Alternativ
 
 Before you begin, have the following tools and services:
 
-+ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/).
-
-+ An Azure Cognitive Search service. [Create a service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices). You can use a free service for this quickstart. 
++ [Visual Studio Code](https://code.visualstudio.com) or another IDE
 
 + [Node.js](https://nodejs.org) and [npm](https://www.npmjs.com)
 
-+ [Visual Studio Code](https://code.visualstudio.com) or another IDE
++ Azure Cognitive Search. [Create a service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices). 
+
+You can use a free service for this quickstart. 
 
 ## Set up your project
 

articles/search/media/search-security-overview/create-query-key.png

@@ -1,106 +1,169 @@
 ---
-title: API key authentication
+title: Connect with API keys
 titleSuffix: Azure Cognitive Search
-description: An API key controls inbound access to the service endpoint. Admin keys grant write access. Query keys can be created for read-only access.
+description: Learn how to use an admin or query API key for inbound access to an Azure Cognitive Search service endpoint.
 
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
-ms.topic: conceptual
-ms.date: 08/15/2022
+ms.topic: how-to
+ms.date: 01/10/2023
 ---
 
-# Use API keys for Azure Cognitive Search authentication
+# Connect to Cognitive Search using key authentication
 
-Cognitive Search offers key-based authentication as its primary authentication methodology. For inbound requests to a search service endpoint, such as requests that create or query an index, API keys are the only generally available authentication option you have. A few outbound request scenarios, particularly those involving indexers, can use Azure Active Directory identities and roles.
+Cognitive Search offers key-based authentication that you can use on connections to your search service. An API key is a unique string composed of 52 randomly generated numbers and letters. A request made to a search service endpoint will be accepted if both the request and the API key are valid.
+
+API keys are frequently used when making REST API calls to a search service. You can also use them in search solutions if Azure Active Directory isn't an option.
 
 > [!NOTE]
-> [Azure role-based access control (RBAC)](search-security-rbac.md) for inbound requests to a search endpoint is now in preview. You can use this preview capability to supplement or replace API keys on search index requests.
+> A quick note about "key" terminology in Cognitive Search. An "API key", which is described in this article, refers to a GUID used for authenticating a request. A "document key" refers to a unique string in your indexed content that's used to uniquely identify documents in a search index. API keys and document keys are unrelated.
 
-## Using API keys in search
+## What's an API key?
 
-API keys are generated when the service created. Passing a valid API key on the request is considered proof that the request is from an authorized client. There are two kinds of keys. *Admin keys* convey write permissions on the service and also grant rights to query system information. *Query keys* convey read permissions and can be used by apps to query a specific index. 
+There are two kinds of keys used for authenticating a request:
 
-When connecting to a search service, all requests must include an API key that was generated specifically for your service.
+| Type | Permission level | Maximum | How created|
+|------|------------------|---------|---------|
+| Admin | Full access (read-write) for all content operations | 2 <sup>1</sup>| Two admin keys, referred to as *primary* and *secondary* keys in the portal, are generated when the service is created and can be individually regenerated on demand. |
+| Query | Read-only access, scoped to the documents collection of a search index | 50 | One query key is generated with the service. More can be created on demand by a search service administrator. |
 
-+ In [REST solutions](search-get-started-rest.md), the API key is typically specified in a request header
+<sup>1</sup>  Having two allows you to roll over one key while using the second key for continued access to the service.
 
-+ In [.NET solutions](search-howto-dotnet-sdk.md), a key is often specified as a configuration setting and then passed as an [AzureKeyCredential](/dotnet/api/azure.azurekeycredential)
+Visually, there's no distinction between an admin key or query key. Both keys are strings composed of 52 randomly generated alpha-numeric characters. If you lose track of what type of key is specified in your application, you can [check the key values in the portal](#find-existing-keys).
 
-You can view and manage API keys in the [Azure portal](https://portal.azure.com), or through [PowerShell](/powershell/module/az.search), [Azure CLI](/cli/azure/search), or [REST API](/rest/api/searchmanagement/).
+## Use API keys on connections
+
+API keys are specified on client requests to a search service. Passing a valid API key on the request is considered proof that the request is from an authorized client. If you're creating, modifying, or deleting objects, you'll need an admin API key. Otherwise, query keys are typically distributed to client applications that issue queries.
+
+You can specify API keys in a request header for REST API calls, or in code that calls the azure.search.documents client libraries in the Azure SDKs. If you're using the Azure portal to perform tasks, your role assignment determines the level of access.
+
+Best practices for using hard-coded in source files include:
+
++ During early development and proof-of-concept testing when security is looser, use sample or public data.
+
++ After advancing into deeper development or production scenarios, switch to [Azure Active Directory and role-based access](search-security-rbac.md) to eliminate the need for having hard-coded keys. Or, if you want to continue using API keys, be sure to always monitor who has access to your API keys and regenerate API keys on a regular cadence.
+
+### [**REST**](#tab/rest-use)
+
++ Admin keys are only specified in HTTP request headers. You can't place an admin API key in a URL. See [Connect to Azure Cognitive Search using REST APIs](search-get-started-rest.md#connect-to-azure-cognitive-search) for an example that specifies an admin API key on a REST call.
+
++ Query keys are also specified in an HTTP request header for search, suggestion, or lookup operation that use POST.
 
-:::image type="content" source="media/search-manage/azure-search-view-keys.png" alt-text="Portal page, retrieve settings, keys section" border="false":::
+  Alternatively, you can pass a query key  as a parameter on a URL if you're using GET: `GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]`
 
-## What is an API key?
+### [**Azure PowerShell**](#tab/azure-ps-use)
 
-An API key is a unique string composed of randomly generated numbers and letters that are passed on every request to the search service. The service will accept the request, if both the request itself and the key are valid. 
+A script example showing API key usage can be found at [Quickstart: Create an Azure Cognitive Search index in PowerShell using REST APIs](search-get-started-powershell.md).
 
-Two types of keys are used to access your search service: admin (read-write) and query (read-only).
+### [**.NET**](#tab/dotnet-use)
 
-|Key|Description|Limits|  
-|---------|-----------------|------------|  
-|Admin|Grants full rights to all operations, including the ability to manage the service, create and delete indexes, indexers, and data sources.<br /><br /> Two admin keys, referred to as *primary* and *secondary* keys in the portal, are generated when the service is created and can be individually regenerated on demand. Having two keys allows you to roll over one key while using the second key for continued access to the service.<br /><br /> Admin keys are only specified in HTTP request headers. You cannot place an admin API key in a URL.|Maximum of 2 per service|  
-|Query|Grants read-only access to indexes and documents, and are typically distributed to client applications that issue search requests.<br /><br /> Query keys are created on demand.<br /><br /> Query keys can be specified  in an HTTP request header for search, suggestion, or lookup operation. Alternatively, you can pass a query key  as a parameter on a URL. Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:<br /><br /> `GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]`|50 per service|  
+In search solutions, a key is often specified as a configuration setting and then passed as an [AzureKeyCredential](/dotnet/api/azure.azurekeycredential). See [How to use Azure.Search.Documents in a C# .NET Application](search-howto-dotnet-sdk.md) for an example.
 
- Visually, there is no distinction between an admin key or query key. Both keys are strings composed of 32 randomly generated alpha-numeric characters. If you lose track of what type of key is specified in your application, you can [check the key values in the portal](https://portal.azure.com).  
+---
 
 > [!NOTE]  
-> It's considered a poor security practice to pass sensitive data such as an `api-key` in the request URI. For this reason, Azure Cognitive Search only accepts a query key as an `api-key` in the query string, and you should avoid doing so unless the contents of your index should be publicly available. As a general rule, we recommend passing your `api-key` as a request header.  
+> It's considered a poor security practice to pass sensitive data such as an `api-key` in the request URI. For this reason, Azure Cognitive Search only accepts a query key as an `api-key` in the query string. As a general rule, we recommend passing your `api-key` as a request header.  
 
 ## Find existing keys
 
-You can obtain access keys in the portal or through [PowerShell](/powershell/module/az.search), [Azure CLI](/cli/azure/search), or [REST API](/rest/api/searchmanagement/).
+You can view and manage API keys in the [Azure portal](https://portal.azure.com), or through [PowerShell](/powershell/module/az.search), [Azure CLI](/cli/azure/search), or [REST API](/rest/api/searchmanagement/).
+
+### [**Azure portal**](#tab/portal-find)
+
+1. Sign in to the [Azure portal](https://portal.azure.com) and [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
+
+1. Under **Settings**, select **Keys** to view admin and query keys.
 
-1. Sign in to the [Azure portal](https://portal.azure.com).
-1. List the [search services](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) for your subscription.
-1. Select the service and on the Overview page, click **Settings** >**Keys** to view admin and query keys.
+:::image type="content" source="media/search-manage/azure-search-view-keys.png" alt-text="Screenshot of a portal page showing API keys." border="true":::
 
-   :::image type="content" source="media/search-security-overview/settings-keys.png" alt-text="Portal page, view settings, keys section" border="false":::
+### [**REST**](#tab/rest-find)
+
+Use [ListAdminKeys](/rest/api/searchmanagement/2020-08-01/admin-keys) or [ListQueryKeys](/rest/api/searchmanagement/2020-08-01/query-keys/list-by-search-service) in the Management REST API to return API keys.
+
+You must have a [valid role assignment](#permissions-to-view-or-manage-api-keys) to return or update API keys. See [Manage your Azure Cognitive Search service with REST APIs](search-manage-rest.md) for guidance on meeting role requirements using the REST APIs.
+
+```rest
+POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2021-04-01-preview
+```
+
+---
 
 ## Create query keys
 
 Query keys are used for read-only access to documents within an index for operations targeting a documents collection. Search, filter, and suggestion queries are all operations that take a query key. Any read-only operation that returns system data or object definitions, such as an index definition or indexer status, requires an admin key.
 
 Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Always use a query key rather than an admin key for any query originating from a client app.
 
-1. Sign in to the [Azure portal](https://portal.azure.com).
-2. List the [search services](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices)  for your subscription.
-3. Select the service and on the Overview page, click **Settings** >**Keys**.
-4. Click **Manage query keys**.
-5. Use the query key already generated for your service, or create up to 50 new query keys. The default query key is not named, but additional query keys can be named for manageability.
+### [**Azure portal**](#tab/portal-query)
 
-   :::image type="content" source="media/search-security-overview/create-query-key.png" alt-text="Create or use a query key" border="false":::
+1. Sign in to the [Azure portal](https://portal.azure.com) and [find your search service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices).
 
-> [!Note]
-> A code example showing query key usage can be found in [DotNetHowTo](https://github.com/Azure-Samples/search-dotnet-getting-started/tree/master/DotNetHowTo).
+1. Under **Settings**, select **Keys** to view API keys.
+
+1. Under **Manage query keys**, use the query key already generated for your service, or create new query keys. The default query key isn't named, but other generated query keys can be named for manageability.
+
+   :::image type="content" source="media/search-security-overview/create-query-key.png" alt-text="Screenshot of the query key management options." border="true":::
+
+### [**Azure CLI**](#tab/azure-cli-query)
+
+A script example showing query key usage can be found at [Create or delete query keys](search-manage-azure-cli.md#create-or-delete-query-keys).
+
+### [**.NET**](#tab/dotnet-query)
+
+A code example showing query key usage can be found in [DotNetHowTo](https://github.com/Azure-Samples/search-dotnet-getting-started/tree/master/DotNetHowTo).
+
+---
 
 <a name="regenerate-admin-keys"></a>
 
 ## Regenerate admin keys
 
-Two admin keys are created for each service so that you can rotate a primary key, using the secondary key for business continuity.
+Two admin keys are created for each service so that you can rotate a primary key while using the secondary key for business continuity.
+
+1. In the **Settings** > **Keys** page, copy the secondary key.
+
+1. For all applications, update the API key settings to use the secondary key.
 
-1. In the **Settings** >**Keys** page, copy the secondary key.
-2. For all applications, update the API key settings to use the secondary key.
-3. Regenerate the primary key.
-4. Update all applications to use the new primary key.
+1. Regenerate the primary key.
 
-If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. However, content is not deleted and you are not locked out permanently. 
+1. Update all applications to use the new primary key.
 
-You can still access the service through the portal or programmatically. Management functions are operative through a subscription ID not a service API key, and thus still available even if your API keys are not. 
+If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. However, content isn't deleted and you aren't locked out permanently. 
 
-After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you have the new keys and provide those keys on requests.
+You can still access the service through the portal or programmatically. Management functions are operative through a subscription ID not a service API key, and are thus still available even if your API keys aren't. 
 
-## Secure API keys
+After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you provide those keys on requests.
 
-[Role assignments](search-security-rbac.md) determine who can read and manage keys. Members of the following roles can view and regenerate keys: Owner, Contributor, [Search Service Contributors](../role-based-access-control/built-in-roles.md#search-service-contributor). The Reader role does not have access to API keys.
+## Permissions to view or manage API keys
 
-Subscription administrators can view and regenerate all API keys. As a precaution, review role assignments to understand who has access to the admin keys.
+Permissions for viewing and managing API keys is conveyed through [role assignments](search-security-rbac.md). Members of the following roles can view and regenerate keys:
+
++ Administrator and co-administrator (classic)
++ Owner
++ Contributor
++ [Search Service Contributors](../role-based-access-control/built-in-roles.md#search-service-contributor) 
+
+The following roles don't have access to API keys:
+
++ Reader
++ Search Index Data Contributor
++ Search Index Data Reader
+
+## Secure API key access
+
+Use role assignments to restrict access to API keys.
+
+Note that it's not possible to use [customer-managed key encryption](search-security-manage-encryption-keys.md) to encrypt API keys. Only sensitive data within the search service itself (for example, index content or connection strings in data source object definitions) can be CMK-encrypted.
 
 1. Navigate to your search service page in Azure portal.
+
 1. On the left navigation pane, select **Access control (IAM)**, and then select the **Role assignments** tab.
-1. Set **Scope** to **This resource** to view role assignments for your service.
+
+1. In the **Role** filter, select the roles that have permission to view or manage keys (Owner, Contributor, Search Service Contributor). The resulting security principals assigned to those roles have key permissions on your search service.
+
+1. As a precaution, also check the **Classic administrators** tab for administrators and co-administrators.
 
 ## See also