Edit

Share via

Quickstart: Connect to a search service

In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to establish a keyless connection to your Azure AI Search service. You then use Python in Visual Studio Code to interact with your service.

Keyless connections provide enhanced security through granular permissions and identity-based authentication. We don't recommend hard-coded API keys, but if you prefer them, see Connect to Azure AI Search using keys.

Prerequisites

Configure role-based access

In this section, you enable RBAC on your Azure AI Search service and assign the necessary roles for creating, loading, and querying search objects. For more information about these steps, see Connect to Azure AI Search using roles.

To configure access:

  1. Sign in to the Azure portal and select your search service.

  2. From the left pane, select Settings > Keys.

  3. Select Role-based access control or Both if you need time to transition clients to RBAC.

    Screenshot of the access control options in the Azure portal.

  4. From the left pane, select Access control (IAM).

  5. Select Add > Add role assignment.

    Screenshot of the dropdown menu for adding a role assignment in the Azure portal.

  6. Assign the Search Service Contributor role to your user account or managed identity.

  7. Repeat the role assignment for Search Index Data Contributor.

Get service information

In this section, you retrieve the subscription ID and endpoint of your Azure AI Search service. If you only have one subscription, skip the subscription ID and only retrieve the endpoint. You use these values in the remaining sections of this quickstart.

To get your service information:

  1. Sign in to the Azure portal and select your search service.

  2. From the left pane, select Overview.

  3. Make a note of the subscription ID and endpoint.

    Screenshot of the subscription ID and endpoint in the Azure portal.

Sign in to Azure

Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service. This step establishes your Microsoft Entra identity, which DefaultAzureCredential uses to authenticate requests in the next section.

To sign in:

  1. On your local system, open a command-line tool.

  2. Check the active subscription and tenant in your local environment.

    az account show

  3. If the active subscription and tenant aren't valid for your search service, run the following commands to update their values. You can find the subscription ID on the search service Overview page in the Azure portal. To find the tenant ID, select the name of your subscription on the Overview page, and then locate the Parent management group value.

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

Note

This section illustrates the basic Python pattern for keyless connections. For comprehensive guidance, see a specific quickstart or tutorial, such as Quickstart: Use agentic retrieval in Azure AI Search.

You can use Python notebooks in Visual Studio Code to send requests to your Azure AI Search service. For request authentication, use the DefaultAzureCredential class from the Azure Identity library.

To connect using Python:

  1. On your local system, open Visual Studio Code.

  2. Create a .ipynb file.

  3. Create a code cell to install the azure-identity and azure-search-documents libraries.

    pip install azure-identity azure-search-documents

  4. Create another code cell to authenticate and connect to your search service.

    from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
credential = DefaultAzureCredential()
client = SearchIndexClient(endpoint = service_endpoint, credential = credential)

# List existing indexes
indexes = client.list_indexes()

for index in indexes:
   index_dict = index.as_dict()
   print(json.dumps(index_dict, indent = 2))

  5. Set service_endpoint to the value you obtained in Get service information.

  6. Select Run All to run both code cells.

    The output should list the existing indexes (if any) on your search service, indicating a successful connection.

Troubleshoot 401 errors

If you encounter a 401 error, follow these troubleshooting steps:

  • Revisit Configure role-based access. Your search service must have Role-based access control or Both enabled. Policies at the subscription or resource group level might override your role assignments.

  • Revisit Sign in to Azure. You must sign in to the subscription that contains your search service.

  • Make sure your endpoint variable has surrounding quotes.

  • If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with Sign in to Azure.

In this quickstart, you use role-based access control (RBAC) and Microsoft Entra ID to establish a keyless connection to your Azure AI Search service. You then use REST in Visual Studio Code to interact with your service.

Keyless connections provide enhanced security through granular permissions and identity-based authentication. We don't recommend hard-coded API keys, but if you prefer them, see Connect to Azure AI Search using keys.

Prerequisites

Configure role-based access

In this section, you enable RBAC on your Azure AI Search service and assign the necessary roles for creating, loading, and querying search objects. For more information about these steps, see Connect to Azure AI Search using roles.

To configure access:

  1. Sign in to the Azure portal and select your search service.

  2. From the left pane, select Settings > Keys.

  3. Select Role-based access control or Both if you need time to transition clients to RBAC.

    Screenshot of the access control options in the Azure portal.

  4. From the left pane, select Access control (IAM).

  5. Select Add > Add role assignment.

    Screenshot of the dropdown menu for adding a role assignment in the Azure portal.

  6. Assign the Search Service Contributor role to your user account or managed identity.

  7. Repeat the role assignment for Search Index Data Contributor.

Get service information

In this section, you retrieve the subscription ID and endpoint of your Azure AI Search service. If you only have one subscription, skip the subscription ID and only retrieve the endpoint. You use these values in the remaining sections of this quickstart.

To get your service information:

  1. Sign in to the Azure portal and select your search service.

  2. From the left pane, select Overview.

  3. Make a note of the subscription ID and endpoint.

    Screenshot of the subscription ID and endpoint in the Azure portal.

Sign in to Azure

Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service.

To sign in:

  1. On your local system, open a command-line tool.

  2. Check the active subscription and tenant in your local environment.

    az account show

  3. If the active subscription and tenant aren't valid for your search service, run the following commands to update their values. You can find the subscription ID on the search service Overview page in the Azure portal. To find the tenant ID, select the name of your subscription on the Overview page, and then locate the Parent management group value.

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

Get token

REST API calls require the inclusion of a Microsoft Entra ID token. You use this token to authenticate requests in the next section.

To get your token:

  1. Using the same command-line tool, generate an access token.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

  2. Make a note of the token output.

Note

This section illustrates the basic REST pattern for keyless connections. For comprehensive guidance, see a specific quickstart or tutorial, such as Quickstart: Use agentic retrieval in Azure AI Search.

You can use the REST Client extension in Visual Studio Code to send requests to your Azure AI Search service. For request authentication, include an Authorization header with the Microsoft Entra ID token you previously generated.

To connect using REST:

  1. On your local system, open Visual Studio Code.

  2. Create a .rest or .http file.

  3. Paste the following variables and request into the file.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

### List existing indexes
GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Set @baseUrl to the value you obtained in Get service information.

  5. Set @token to the value you obtained in Get token.

  6. Under ### List existing indexes, select Send Request.

    You should receive an HTTP/1.1 200 OK response, indicating a successful connection to your search service.

Troubleshoot 401 errors

If you encounter a 401 error, follow these troubleshooting steps:

  • Revisit Configure role-based access. Your search service must have Role-based access control or Both enabled. Policies at the subscription or resource group level might override your role assignments.

  • Revisit Sign in to Azure. You must sign in to the subscription that contains your search service.

  • Make sure your endpoint and token variables don't have surrounding quotes or extra spaces.

  • Make sure your token doesn't have the @ symbol in the request header. For example, if the variable is @token, the reference in the request should be {{token}}.

  • If all else fails, restart your device to remove cached tokens and then repeat the steps in this quickstart, starting with Sign in to Azure.

Related content

  • Last updated on