Use role-based authorization in Azure Cognitive Search

Azure provides a global role-based access control (RBAC) authorization system for all services running on the platform. In Cognitive Search, you can use role authorization in the following ways:

  • Allow access to control plane operations, such as adding capacity or rotating keys, on the search service itself through Owner, Contributor, and Reader roles.

  • Allow access to data plane operations, such as creating or querying indexes. This capability is currently in public preview (by request). After your subscription is on-boarded, follow the instructions in this article to use the feature.

  • Allow outbound indexer connections to be made using a managed identity. For a search service that has a managed identity assigned to it, you can create roles assignments that extend external data services, such as Azure Blob Storage, to allow read access on blobs by your trusted search service.

This article focuses on the first two bullets, roles for control plane and data plane operations..

A few RBAC scenarios are not directly supported, and these include:

  • Custom roles

  • User identity access over search results (sometimes referred to as row-level security or document-level security)

    Tip

    For document-level security, a workaround is to use security filters to trim results by user identity, removing documents for which the requestor should not have access.

Built-in roles include generally available and preview roles, whose assigned membership consists of Azure Active Directory users and groups.

Role assignments are cumulative and pervasive across all tools and client libraries used to create or manage a search service. Clients include the Azure portal, Management REST API, Azure PowerShell, Azure CLI, and the management client library of Azure SDKs.

There are no regional, tier, or pricing restrictions for using RBAC on Azure Cognitive Search, but your search service must be in the Azure public cloud.

Role Applies to Description
Owner Service ops (generally available) Full access to the search resource, including the ability to assign Azure roles. Subscription administrators are members by default.
Contributor Service ops (generally available) Same level of access as Owner, minus the ability to assign roles or change authorization options.
Reader Service ops (generally available) Limited access to partial service information. In the portal, the Reader role can access information in the service Overview page, in the Essentials section and under the Monitoring tab. All other tabs and pages are off limits.

This role has access to service information: resource group, service status, location, subscription name and ID, tags, URL, pricing tier, replicas, partitions, and search units.

This role also has access to service metrics: search latency, percentage of throttled requests, average queries per second.

There is no access to API keys, role assignments, content (indexes or synonym maps), or content metrics (storage consumed, number of objects).
Search Service Contributor Service ops (generally available), and top-level objects (preview) This role is a combination of Contributor at the service-level, but with full access to all actions on indexes, synonym maps, indexers, data sources, and skillsets through Microsoft.Search/searchServices/*. This role is for search service administrators who need to fully manage the service.

Like Contributor, members of this role cannot make or manage role assignments or change authorization options.
Search Index Data Contributor Documents collection (preview) Provides full access to content in all indexes on the search service. This role is for developers or index owners who need to import, refresh, or query the documents collection of an index.
Search Index Data Reader Documents collection (preview) Provides read-only access to search indexes on the search service. This role is for apps and users who run queries.

Scope: control plane and data plane

Azure resources have the concept of control plane and data plane categories of operations. The built-in roles for Cognitive Search apply to either one plane or the other.

Category Operations
Control plane Operations include create, update, and delete services, manage API keys, adjust partitions and replicas, and so forth. The Management REST API and equivalent client libraries define the operations applicable to the control plane.
Data plane Operations against the search service endpoint, encompassing all objects and data hosted on the service. Indexing, querying, and all associated actions target the data plane, which is accessed via the Search REST API and equivalent client libraries.

Currently, you cannot use role assignments to restrict access to individual indexes, synonym maps, indexers, data sources, or skillsets.

Configure Search for data plane authentication

If you are using any of the preview data plane roles (Search Index Data Contributor or Search Index Data Reader) and Azure AD authentication, your search service must be configured to recognize an authorization header on data requests that provide an OAuth2 access token. This section explains how to configure your search service. If you are using control plane roles (Owner, Contributor, Reader), you can skip this step.

Before you start, sign up for the RBAC preview. Your subscription must be enrolled into the program before you can use this feature. It can take up to two business days to process enrollment requests. You'll receive an email when your service is ready.

  1. Open the portal with this syntax: https://portal.azure.cn/?feature.enableRbac=true.

  2. Navigate to your search service.

  3. Select Keys in the left navigation pane.

  4. Choose an API access control mechanism. If you don't see these options, check the portal URL. If you can't save your selection, there is an issue with subscription enrollment.

    Option Status Description
    API Key Generally available (default) Requires an admin or query API keys 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. Choosing this option limits you to clients that support the 2021-04-30-preview REST API.
    Both Preview Requests are valid using either an API key or an authorization token.

Once your search service is RBAC-enabled, the portal will require the feature flag in the URL for assigning roles and viewing content. Content, such as indexes and indexers, will only be visible in the portal if you open it with the feature flag. If you want to restore the default behavior at a later date, revert the API Keys selection to API Keys.

Assign roles

Roles can be assigned using any of the supported approaches described in Azure role-based access control documentation.

When using PowerShell to assign roles, call New-AzRoleAssignment, providing the Azure user or group name, and the scope of the assignment.

Before you start, make sure you load the Azure and AzureAD modules and connect to Azure:

Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount -Environment AzureChinaCloud

Scoped to the service, your syntax should look similar to the following example:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Scoped to an individual index:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Recall that you can only scope access to top-level resources, such as indexes, synonym maps, indexers, data sources, and skillsets. You can't control access to search documents (index content) with Azure roles.