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. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in Get service information.

    az login

Note

This section illustrates the basic Python pattern for keyless connections. For comprehensive guidance, see a specific quickstart or tutorial, such as Quickstart: Run 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 also 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.

Get token

Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service and generate a Microsoft Entra ID token. You use this token to authenticate requests in the next section.

To get your token:

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

  2. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in Get service information.

    az login

  3. Generate an access token.

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

  4. 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: Run 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 placeholders 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=2024-07-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. Replace @baseUrl with the value you obtained in Get service information.

  5. Replace @token with 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 also override your role assignments.

  • Revisit Get token. 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 Get token.

Related content