Merge pull request #2342 from eric-urban/eur/azs-auth-keys-308923

prmerger-automator[bot] · web-flow · commit 6e3f583096bc · 2025-01-17T18:05:38.000Z
AzS: Authenticate with keys refresh
diff --git a/articles/search/search-security-api-keys.md b/articles/search/search-security-api-keys.md
@@ -2,24 +2,23 @@
 title: Connect using API keys
 titleSuffix: Azure AI Search
 description: Learn how to use an admin or query API key for inbound access to an Azure AI Search service endpoint.
-
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 10/30/2024
+ms.date: 1/16/2025
+#customer intent: I want to learn how to connect to Azure AI Search using API keys so that I can authenticate inbound requests to my search service.
 ---
 
 # Connect to Azure AI Search using keys
 
-Azure AI Search offers key-based authentication for connections to your search service. An API key is a unique string composed of 52 randomly generated numbers and letters. In your source code, you can specify it as an [environment variable](/azure/ai-services/cognitive-services-environment-variables) or as an app setting in your project, and then reference the variable on the request. A request made to a search service endpoint is accepted if both the request and the API key are valid.
-
-Key-based authentication is the default. 
+Azure AI Search supports both keyless and key-based authentication for connections to your search service. An API key is a unique string composed of 52 randomly generated numbers and letters. In your source code, you can specify it as an [environment variable](/azure/ai-services/cognitive-services-environment-variables) or as an app setting in your project, and then reference the variable on the request. A request made to a search service endpoint is accepted if both the request and the API key are valid.
 
-You can replace it with [role-based access](search-security-enable-roles.md), which eliminates the need for hardcoded keys in your codebase.
+> [!IMPORTANT]
+> When you create a search service, key-based authentication is the default, but it's not the most secure option. We recommend that you replace it with [role-based access](search-security-enable-roles.md).
 
 ## Types of API keys
 
@@ -36,11 +35,11 @@ Visually, there's no distinction between an admin key or query key. Both keys ar
 
 ## Use API keys on connections
 
-API keys are used for data plane (content) requests, such as creating or accessing an index or, any other request that's represented in the [Search REST APIs](/rest/api/searchservice/). Upon service creation, an API key is the only authentication mechanism for data plane operations, but you can replace or supplement key authentication with [Azure roles](search-security-rbac.md) if you can't use hard-coded keys in your code.
-
-Admin keys are used for creating, modifying, or deleting objects. Admin keys are also used to GET object definitions and system information.
+API keys are used for data plane (content) requests, such as creating or accessing an index or, any other request that's represented in the [Search REST APIs](/rest/api/searchservice/). 
 
-Query keys are typically distributed to client applications that issue queries.
+You can use either an API key or [Azure roles](search-security-rbac.md) for management plane (service) requests. When you use an API key:
+- Admin keys are used for creating, modifying, or deleting objects. Admin keys are also used to GET object definitions and system information.
+- Query keys are typically distributed to client applications that issue queries.
 
 ### [**REST API**](#tab/rest-use)
 
@@ -241,11 +240,13 @@ It's not possible to use [customer-managed key encryption](search-security-manag
 
 ## Best practices
 
++ For production workloads, switch to [Microsoft Entra ID and role-based access](keyless-connections.md). Or, if you want to continue using API keys, be sure to always monitor [who has access to your API keys](#secure-api-keys) and [regenerate API keys](#regenerate-admin-keys) on a regular cadence.
+
 + Only use API keys if data disclosure isn't a risk (for example, when using sample data) and if you're operating behind a firewall. Exposure of API keys is a risk to both data and to unauthorized use of your search service. 
 
-+ Always check code, samples, and training material before publishing to make sure you didn't leave valid API keys behind.
++ If you use an API key, store it securely somewhere else, such as in [Azure Key Vault](/azure/key-vault/general/overview). Don't include the API key directly in your code, and never post it publicly.
 
-+ For production workloads, switch to [Microsoft Entra ID and role-based access](keyless-connections.md). Or, if you want to continue using API keys, be sure to always monitor [who has access to your API keys](#secure-api-keys) and [regenerate API keys](#regenerate-admin-keys) on a regular cadence.
++ Always check code, samples, and training material before publishing to make sure you don't inadvertently expose an API key.
 
 ## See also
 
diff --git a/articles/search/search-security-enable-roles.md b/articles/search/search-security-enable-roles.md
@@ -2,19 +2,21 @@
 title: Enable role-based access control
 titleSuffix: Azure AI Search
 description: Enable or disable role-based access control for token authentication using Microsoft Entra ID on Azure AI Search.
-
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 10/30/2024
-
+ms.date: 1/16/2025
+#customer intent: As a developer, I want to enable role-based access control for token authentication using Microsoft Entra ID on Azure AI Search so that I can secure my search service.
 ---
 
 # Enable or disable role-based access control in Azure AI Search
 
-Azure AI Search uses [key-based authentication](search-security-api-keys.md) by default, but it fully supports Microsoft Entra ID authentication and authorization for all control plane and data plane operations through Azure role-based access control (RBAC).
+Azure AI Search supports both keyless and [key-based authentication](search-security-api-keys.md) for for all control plane and data plane operations. You can use Microsoft Entra ID authentication and authorization for all control plane and data plane operations through Azure role-based access control (RBAC).
+
+> [!IMPORTANT]
+> When you create a search service, key-based authentication is the default, but it's not the most secure option. We recommend that you replace it with role-based access as described in this article.
 
 Before you can assign roles for authorized data plane access to Azure AI Search, you must enable role-based access control on your search service. Roles for service administration (control plane) are built in and can't be enabled or disabled. 
 
@@ -37,18 +39,18 @@ The default failure mode for unauthorized requests is `http401WithBearerChalleng
 
 ### [**Azure portal**](#tab/config-svc-portal)
 
-1. Sign in to the [Azure portal](https://portal.azure.com) and open the search service page.
+1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to your search service.
 
 1. Select **Settings** and then select **Keys** in the left navigation pane.
 
    :::image type="content" source="media/search-security-rbac/search-security-enable-roles.png" lightbox="media/search-security-rbac/search-security-enable-roles.png" alt-text="Screenshot of the keys page with authentication options." border="true":::
 
-1. Choose **Role-based control** or **Both** if you're currently using keys and need time to transition clients to role-based access control. 
+1. Choose **Role-based control**. Only choose **Both** if you're currently using keys and need time to transition clients to role-based access control. 
 
    | Option | Description |
    |--------|--------------|
-   | API Key | (default). Requires [API keys](search-security-api-keys.md) on the request header for authorization. |
-   | Role-based access control | Requires membership in a role assignment to complete the task. It also requires an authorization header on the request. |
+   | API Key (default) | Requires [API keys](search-security-api-keys.md) on the request header for authorization. |
+   | Role-based access control (recommended) | Requires membership in a role assignment to complete the task. It also requires an authorization header on the request. |
    | Both | Requests are valid using either an API key or role-based access control, but if you provide both in the same request, the API key is used. |
 
 1. As an administrator, if you choose a roles-only approach, [assign data plane roles](search-security-rbac.md) to your user account to restore full administrative access over data plane operations in the Azure portal. Roles include Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader. You need the first two roles if you want equivalent access.
@@ -140,7 +142,7 @@ All calls to the Management REST API are authenticated through Microsoft Entra I
 
 It's possible to disable role-based access control for data plane operations and use key-based authentication instead. You might do this as part of a test workflow, for example to rule out permission issues.
 
-Reverse the steps you followed previously to enable role-based access.
+To disable role-based access control in the Azure portal:
 
 1. Sign in to the [Azure portal](https://portal.azure.com) and open the search service page.
 
@@ -221,12 +223,6 @@ To re-enable key authentication, set "disableLocalAuth" to false. The search ser
 
 ---
 
-## Effects of role-based access control
-
-+ Role-based access control can increase the latency of some requests. Each unique combination of service resource (index, indexer, skillsets and so forth) and service principal triggers an authorization check. These authorization checks can add up to 200 milliseconds of latency per request. 
-
-+ In rare cases where requests originate from a high number of different service principals, all targeting different service resources (indexes, indexers, and so forth), it's possible for the authorization checks to result in throttling. Throttling would only happen if hundreds of unique combinations of search service resource and service principal were used within a second.
-
 ## Next steps
 
 > [!div class="nextstepaction"]
diff --git a/articles/search/search-security-rbac.md b/articles/search/search-security-rbac.md
@@ -606,12 +606,6 @@ To enable a Conditional Access policy for Azure AI Search, follow these steps:
 > [!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 can't be enforced on a specific search service. Instead make sure you select the general **Azure AI Search** cloud app.
 
-## Limitations
-
-+ Role-based access control can increase the latency of some requests. Each unique combination of service resource (index, indexer, etc.) and service principal triggers an authorization check. These authorization checks can add up to 200 milliseconds of latency per request. 
-
-+ In rare cases where requests originate from a high number of different service principals, all targeting different service resources (indexes, indexers, etc.), it's possible for the authorization checks to result in throttling. Throttling would only happen if hundreds of unique combinations of search service resource and service principal were used within a second.
-
 ## Troubleshooting role-based access control issues
 
 When developing applications that use role-based access control for authentication, some common issues might occur:
