Authorize access to a search app using Azure Active Directory
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.
Open Azure portal and find your search service
On the left-nav pane, select Keys.
In the blue banner that mentions the preview, select Register to add the feature to your subscription.
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.
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.
Navigate to your search service in the Azure portal.
On the left navigation pane, select Keys.
Choose whether to allow both key-based and role-based access control, or only role-based access control.
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.
Sign in to the Azure portal.
Search for Managed Identities.
Select + Create.
Give your managed identity a name and select a region. Then, select Create.
Assign a role to the managed identity
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.
Sign in to the Azure portal.
Navigate to your search service.
Select Access control (IAM) in the left navigation pane.
Select + Add > Add role assignment.
Select an applicable role:
- 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.
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.
On the Members tab, select the managed identity that you want to give access to your search service.
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.
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.
The sample currently uses key-based authentication and the
AzureKeyCredentialto create the
SearchIndexClientbut you can make a small change to switch over to role-based authentication.
Next, import the Azure.Identity library to get access to other authentication techniques.
Instead of using
AzureKeyCredentialin the beginning of
Main()in Program.cs, use
DefaultAzureCredentiallike 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());
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.
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".
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.
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.