Edit

Connect to Azure Cognitive Search using Azure role-based access control (Azure RBAC)

  • Article
  • 16 minutes to read

Azure provides a global role-based access control authorization system for all services running on the platform. In Cognitive Search, you can:

  • Use generally available roles for service administration.

  • Use new preview roles for data requests, including creating, loading, and querying indexes.

Per-user access over search results (sometimes referred to as row-level security or document-level security) isn't supported. As a workaround, create security filters that trim results by user identity, removing documents for which the requestor shouldn't have access.

Built-in roles include generally available and preview roles. If these roles are insufficient, create a custom role instead.

Role Description and availability
Owner (Generally available) Full access to the search resource, including the ability to assign Azure roles. Subscription administrators are members by default.

(Preview) This role has the same access as the Search Service Contributor role on the data plane. It includes access to all data plane actions except the ability to query the search index or index documents.
Contributor (Generally available) Same level of access as Owner, minus the ability to assign roles or change authorization options.

(Preview) This role has the same access as the Search Service Contributor role on the data plane. It includes access to all data plane actions except the ability to query the search index or index documents.
Reader (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: service name, 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.

This role doesn't allow access to API keys, role assignments, content (indexes or synonym maps), or content metrics (storage consumed, number of objects).

(Preview) When you enable the RBAC preview for the data plane, the Reader role has read access across the entire service. This allows you to read search metrics, content metrics (storage consumed, number of objects), and the definitions of data plane resources (indexes, indexers, etc.). The Reader role still won't have access to read API keys or read content within indexes.
Search Service Contributor (Generally available) This role is identical to the Contributor role and applies to control plane operations.

(Preview) When you enable the RBAC preview for the data plane, this role also provides full access to all data plane actions on indexes, synonym maps, indexers, data sources, and skillsets as defined by Microsoft.Search/searchServices/*. This role doesn't give you access to query search indexes or index documents. This role is for search service administrators who need to manage the search service and its objects, but without the ability to view or access object data.

Like Contributor, members of this role can't make or manage role assignments or change authorization options. To use the preview capabilities of this role, your service must have the preview feature enabled, as described in this article.
Search Index Data Contributor (Preview) Provides full data plane 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 (Preview) Provides read-only data plane 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.

Preview capabilities and limitations

  • Role-based access control for data plane operations, such as creating an index or querying an index, is currently in public preview and available under supplemental terms of use.

  • There are no regional, tier, or pricing restrictions for using Azure RBAC preview, but your search service must be in the Azure public cloud. The preview isn't available in Azure Government, Azure Germany, or Azure China 21Vianet.

  • If you migrate your Azure subscription to a new tenant, the Azure RBAC preview will need to be re-enabled.

  • Adoption of role-based access control might increase the latency of some requests. Each unique combination of service resource (index, indexer, etc.) and service principal used on a request will trigger an authorization check. These authorization checks can add up to 200 milliseconds of latency to a 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.

  • Role-based access control is supported in Azure portal and in the following search clients:

Configure role-based access for data plane

Applies to: Search Index Data Contributor, Search Index Data Reader, 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. Sign in to Azure portal and open the search service page.

  2. Select Keys in the left navigation pane.

    Screenshot of the keys page with authentication options.

  3. Choose an API access control option. We recommend Both if you want flexibility or need to migrate apps.

    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.
    Both Preview Requests are valid using either an API key or role-based access control.

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.

Assign roles

Role assignments are cumulative and pervasive across all tools and client libraries. You can assign roles 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.

Role assignments in the portal are service-wide. If you want to grant permissions to a single index, use PowerShell or the Azure CLI instead.

  1. Open the Azure portal.

  2. Navigate to your search service.

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

  4. Select + Add > Add role assignment.

    Access control (IAM) page with Add role assignment menu open.

  5. Select an applicable role:

    • Owner
    • Contributor
    • Reader
    • Search Service Contributor (preview for data plane requests)
    • Search Index Data Contributor (preview)
    • Search Index Data Reader (preview)

  6. On the Members tab, select the Azure AD user or group identity.

  7. On the Review + assign tab, select Review + assign to assign the role.

Test role assignments

When testing roles, remember that roles are cumulative and inherited roles that are scoped to the subscription or resource group can't be deleted or denied at the resource (search service) level.

  1. Open the Azure portal.

  2. Navigate to your search service.

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

    • Members of the Contributor role can view and create any object, but can't query an index using Search Explorer.

    • 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 shouldn't 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.

Grant access to a single index

In some scenarios, you may want to limit application's access to a single resource, such as an index.

The portal doesn't currently support role assignments at this level of granularity, but it can be done with PowerShell or the Azure CLI.

In PowerShell, use New-AzRoleAssignment, providing the Azure user or group name, and the scope of the assignment.

  1. Load the Azure and AzureAD modules and connect to your Azure account:

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

  2. Add a role assignment scoped to an individual index:

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

Create a custom role

If built-in roles don't provide the right combination of permissions, you can create a custom role to support the operations you require

This example clones Search Index Data Reader and then adds the ability to list indexes by name. Normally, listing the indexes on a search service is considered an administrative right.

These steps are derived from Create or update Azure custom roles using the Azure portal. Cloning from an existing role is supported in a search service page.

These steps create a custom role that augments search query rights to include listing indexes by name. Typically, listing indexes is considered an admin function.

  1. In the Azure portal, navigate to your search service.

  2. In the left-navigation pane, select Access Control (IAM).

  3. In the action bar, select Roles.

  4. Right-click Search Index Data Reader (or another role) and select Clone to open the Create a custom role wizard.

  5. On the Basics tab, provide a name for the custom role, such as "Search Index Data Explorer", and then select Next.

  6. On the Permissions tab, select Add permission.

  7. On the Add permissions tab, search for and then select the Microsoft Search tile.

  8. Set the permissions for your custom role. At the top of the page, using the default Actions selection:

    • Under Microsoft.Search/operations, select Read : List all available operations.
    • Under Microsoft.Search/searchServices/indexes, select Read : Read Index.

  9. On the same page, switch to Data actions and under Microsoft.Search/searchServices/indexes/documents, select Read : Read Documents.

    The JSON definition looks like the following example:

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. Select Review + create to create the role. You can now assign users and groups to the role.

Disable API key authentication

API keys can't be deleted, but they can be disabled on your service if you're using the Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader roles and Azure AD authentication. Disabling API keys causes the search service to refuse all data-related requests that pass an API key in the header.

Owner or Contributor permissions are required to disable features.

To disable key-based authentication, use Azure portal or the Management REST API.

  1. In the Azure portal, navigate to your search service.

  2. In the left-navigation pane, select Keys.

  3. Select Role-based access control.

The change is effective immediately, but wait a few seconds before testing. Assuming you have permission to assign roles as a member of Owner, service administrator, or co-administrator, you can use portal features to test role-based access.

Conditional Access

Conditional Access is a tool in Azure Active Directory used to enforce organizational policies. By using Conditional Access policies, you can apply the right access controls when needed to keep your organization secure. When accessing an Azure Cognitive Search service using role-based access control, Conditional Access can enforce organizational policies.

To enable a Conditional Access policy for Azure Cognitive Search, follow the below steps:

  1. Sign in to the Azure portal.

  2. Search for Azure AD Conditional Access.

  3. Select Policies.

  4. Select + New policy.

  5. In the Cloud apps or actions section of the policy, add Azure Cognitive Search as a cloud app depending on how you want to set up your policy.

  6. Update the remaining parameters of the policy. For example, specify which users and groups this policy applies to.

  7. Save the policy.

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 Cognitive Search cloud app.