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 roles in the following ways:

  • Use the generally available roles for service administration, such as adding capacity, monitoring health, or rotating keys. Generally available roles include Owner, Contributor, Reader, and Search Service Contributor.

    Search Service Contributor includes a subset of actions that target content (for example, creating and loading indexes). To enable this subset of actions on Search Service Contributor, follow the steps for preview sign-up.

  • Use the new preview roles for content tasks. Preview roles include Search Index Data Contributor and Search Index Data Reader. This capability is currently in public preview (by request). After enrollment, follow the instructions in this article to use preview roles.

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

This article focuses on the first two bullets: generally available and preview roles. For more information about outbound indexer calls, start with Configure a managed identity.

A few RBAC scenarios are not directly supported:

  • 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.

In Cognitive Search, 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. These clients include the Azure portal, Management REST API, Azure PowerShell, Azure CLI, and the management client library of Azure SDKs.

Roles apply to the search service as a whole and must be assigned by an Owner. You cannot assign roles to specific indexes or other top-level objects.

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 and content (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/* at the content level. This role is for search service administrators who need to fully manage the service and its content. For content management, you must sign up for the preview.

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.

Note

Azure resources have the concept of control plane and data plane categories of operations. In Cognitive Search, "control plane" refers to any operation supported in the Management REST API or equivalent client libraries. The "data plane" refers to operations against the search service endpoint, such as indexing or queries, or any other operation specified in the Search REST API or equivalent client libraries. Most roles apply to just one plane. The exception is Search Service Contributor which supports actions across both.

Step 1: Preview sign-up

Applies to: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

Skip this step if you are using generally available roles (Owner, Contributor, Reader) or just the service-level actions of Search Service Contributor.

New built-in preview roles provide a granular set of permissions over content on the search service. Although built-in roles are always visible in the Azure portal, service enrollment is required to make them operational.

For enrollment into the preview program:

It can take up to two business days to process enrollment requests. You'll receive an email when your service is ready.

Step 2: Preview configuration

Applies to: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

Skip this step if you are using generally available roles (Owner, Contributor, Reader) or just the service-level actions of Search Service Contributor.

In this step, configure your search service to recognize an authorization header on data requests that provide an OAuth2 access token.

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

  2. Navigate to your search service.

  3. Select Keys in the left navigation pane.

  4. Choose an API access control mechanism.

    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.

If you don't see the options, check the portal URL.

If you can't save your selection, or if you get "API access control failed to update for search service <name>. DisableLocalAuth is preview and not enabled for this subscription", your subscription enrollment hasn't been initiated or it hasn't been processed.

Step 3: Assign roles

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

You must be an Owner or have Microsoft.Authorization/roleAssignments/write permissions to manage role assignments.

  1. For preview roles, open the portal with this syntax: 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.

  2. Navigate to your search service.

  3. Select Access Control (IAM) in the left navigation pane.

  4. On the right side, under Grant access to this resource, select Add role assignment.

  5. Find an applicable role and then assign an Azure Active Directory user or group identity:

    • Owner
    • Contributor
    • Reader
    • Search Service Contributor
    • Search Index Data Contributor (preview)
    • Search Index Data Reader (preview)

Step 4: Test

  1. For preview roles, open the portal with this syntax: 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.

  2. Navigate to your search service.

  3. On the Overview page, select the Indexes tab:

    • Members of Search Index Data Reader can use Search Explorer to query the index. You can use any API version to check for access. You should be able to issue queries and view results, but you should not be able to view the index definition.

    • Members of Search Index Data Contributor can select New Index to create a new index. Saving a new index will verify write access on the service.

Disable API key authentication

API keys cannot be deleted, but they can be disabled on your service. If you are using Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader roles and Azure AD authentication, you can disable API keys, causing the search service to refuse all data-related requests that pass an API key in the header for content-related requests.

To disable key-based authentication, use the Management REST API version 2021-04-01-Preview and send two consecutive requests for Update Service.

Owner or Contributor permissions are required to disable features. Use Postman or another web testing tool to complete the following steps (see Tip below):

  1. On the first request, set "AuthOptions" to "aadOrApiKey" to enable Azure AD authentication. Notice that the option indicates availability of either approach: Azure AD or the native API keys.

    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": {
        "authOptions": {
          "aadOrApiKey": {
            "aadAuthFailureMode": "http401WithBearerChallenge"
          }
        }
      }
    }
    
  2. On the second request, set "disableLocalAuth" to true. This step turns off the API key portion of the "aadOrApiKey" option, leaving you with just Azure AD authentication.

    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": {
        "disableLocalAuth": true
      }
    }
    

You cannot combine steps one and two. In step one, "disableLocalAuth" must be false to meet the requirements for setting "AuthOptions", whereas step two changes that value to true.

To re-enable key authentication, rerun the last request, setting "disableLocalAuth" to false. The search service will resume acceptance of API keys on the request automatically (assuming they are specified).

Tip

Management REST API calls are authenticated through Azure Active Directory. For guidance on setting up a security principle and a request, see this blog post Azure REST APIs with Postman (2021). The previous example was tested using the instructions and Postman collection provided in the blog post.