Authorize access to a search app using Azure Active Directory

Important

Role-based access control for data plane operations, such as creating or querying an index, is currently in public preview and available under supplemental terms of use. This functionality is only available in public cloud regions and may impact the latency of your operations while the functionality is in preview. For more information on preview limitations, see RBAC preview limitations.

Search applications that are built on Azure Cognitive Search can now use the Microsoft identity platform for authenticated and authorized access. On Azure, the identity provider is Azure Active Directory (Azure AD). A key benefit of using Azure AD is that your credentials and API keys no longer need to be stored in your code. Azure AD authenticates the security principal (a user, group, or service) running the application. If authentication succeeds, Azure AD returns the access token to the application, and the application can then use the access token to authorize requests to Azure Cognitive Search.

This article shows you how to configure your client for Azure AD:

  • For authentication, you'll create a managed identity as the security principle. You could also use a different type of service principal object, but this article uses managed identities because they eliminate the need to manage credentials.

  • For authorization, you'll assign an Azure role to the managed identity that grants permissions to run queries or manage indexing jobs.

  • Update your client code to call DefaultAzureCredential()

Prepare your search service

As a first step, sign up for the preview and enable role-based access control (RBAC) on your search service.

Sign up for the preview

RBAC for data plane operations is in preview. In this step, add the preview feature to your Azure subscription.

  1. Open Azure portal and find your search service

  2. On the left-nav pane, select Keys.

  3. In the blue banner that mentions the preview, select Register to add the feature to your subscription.

    Screenshot of how to sign up for the rbac preview in the portal

You can also sign up for the preview using Azure Feature Exposure Control (AFEC) and searching for Role Based Access Control for Search Service (Preview). For more information on adding preview features, see Set up preview features in Azure subscription.

Note

Once you add the preview to your subscription, all search services in the subscription are permanently enrolled in the preview. If you don't want RBAC on a given service, you can disable RBAC for data plane operations as shown in a later step.

Enable RBAC for data plane operations

Once your subscription is added to the preview, you'll still need to enable RBAC for data plane operations so that you can use Azure AD authentication. By default, Azure Cognitive Search uses key-based authentication for data plane operations but you can change the setting to allow role-based access control.

  1. Navigate to your search service in the Azure portal.

  2. On the left navigation pane, select Keys.

  3. Choose whether to allow both key-based and role-based access control, or only role-based access control.

    Screenshot of authentication options for azure cognitive search in the portal

You can also change these settings programatically as described in the Azure Cognitive Search RBAC Documentation.

Create a managed identity

In this step, create a managed identity for your client application.

  1. Sign in to the Azure portal.

  2. Search for Managed Identities.

  3. Select + Create.

  4. Give your managed identity a name and select a region. Then, select Create.

    Screenshot of the Create Managed Identity wizard.

Assign a role to the managed identity

Next, you need to grant your managed identity access to your search service. Azure Cognitive Search has various built-in roles. You can also create a custom role.

It's a best practice to grant minimum permissions. If your application only needs to handle queries, you should assign the Search Index Data Reader (preview) role. Alternatively, if it needs both read and write access on a search index, you should use the Search Index Data Contributor (preview) role.

  1. Sign in to 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.

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

  5. Select an applicable role:

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

    For more information on the available roles, see Built-in roles used in Search.

    Note

    The Owner, Contributor, Reader, and Search Service Contributor roles don't give you access to the data within a search index, so you can't query a search index or index data using those roles. For data access to a search index, you need either the Search Index Data Contributor or Search Index Data Reader role.

  6. On the Members tab, select the managed identity that you want to give access to your search service.

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

You can assign multiple roles, such as Search Service Contributor and Search Index Data Contributor, if your application needs comprehensive access to the search services, objects, and content.

You can also assign roles using PowerShell.

Set up Azure AD authentication in your client

Once you have a managed identity and a role assignment on the search service, you're ready to add code to your application to authenticate the security principal and acquire an OAuth 2.0 token.

Azure AD authentication is also supported in the preview SDKs for Java, Python, and JavaScript.

Note

To learn more about the OAuth 2.0 code grant flow used by Azure AD, see Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow.

The Azure SDKs make it easy to integrate with Azure AD. Version 11.4.0-beta.2 and newer of the .NET SDK support Azure AD authentication.

The following instructions reference an existing C# sample to demonstrate the code changes.

  1. As a starting point, clone the source code for the C# quickstart.

    The sample currently uses key-based authentication and the AzureKeyCredential to create the SearchClient and SearchIndexClient but you can make a small change to switch over to role-based authentication.

  2. Next, import the Azure.Identity library to get access to other authentication techniques.

  3. Instead of using AzureKeyCredential in the beginning of Main() in Program.cs, use DefaultAzureCredential like in the code snippet below:

    // Create a SearchIndexClient to send create/delete index commands
    SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
    // Create a SearchClient to load and query documents
    SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
    

Local testing

User-assigned managed identities work only in Azure environments. If you run this code locally, DefaultAzureCredential will fall back to authenticating with your credentials. Make sure you've also given yourself the required access to the search service if you plan to run the code locally.

  1. Verify your account has role assignments to run all of the operations in the quickstart sample. To both create and query an index, you'll need "Search Index Data Reader" and "Search Index Data Contributor".

  2. Go to Tools > Options > Azure Service Authentication to choose your Azure sign-on account.

You should now be able to run the project from Visual Studio on your local system, using role-based access control for authorization.

Note

The Azure.Identity documentation has more details about DefaultAzureCredential and using Azure AD authentication with the Azure SDK for .NET. DefaultAzureCredential is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't served by the default settings should use other credential types.

See also