Udostępnij za pośrednictwem

Korzystanie z usługi Azure AI Search bez kluczy

  • Artykuł

W kodzie aplikacji można skonfigurować bez klucza połączenie z usługą Azure AI Search, które używa identyfikatora i ról firmy Microsoft do uwierzytelniania i autoryzacji. Żądania aplikacji do większości usług platformy Azure muszą być uwierzytelniane za pomocą kluczy lub połączeń bez kluczy. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać kluczy w niezabezpieczonej lokalizacji. Każdy, kto uzyskuje dostęp do klucza, może uwierzytelnić się w usłudze. Uwierzytelnianie bez klucza oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, ponieważ nie ma klucza (lub parametry połączenia) do przechowywania.

Połączenia bez klucza są włączone, wykonując następujące czynności:

  • Skonfiguruj uwierzytelnianie.
  • Ustaw zmienne środowiskowe zgodnie z potrzebami.
  • Użyj typu poświadczeń biblioteki tożsamości platformy Azure, aby utworzyć obiekt klienta usługi Azure AI Search.

Wymagania wstępne

W przypadku obciążeń programowania lokalnego i produkcyjnego należy wykonać następujące czynności:

Tworzenie zasobu wyszukiwania sztucznej inteligencji

Przed kontynuowaniem pracy z tym artykułem potrzebny jest zasób usługi Azure AI Search. Jeśli nie masz zasobu, utwórz teraz zasób . Włącz kontrolę dostępu opartą na rolach (RBAC) dla zasobu.

Instalowanie biblioteki klienta usługi Azure Identity

Aby użyć podejścia bez klucza, zaktualizuj kod z włączoną usługą AI Search za pomocą biblioteki klienta tożsamości platformy Azure.

Zainstaluj bibliotekę klienta usługi Azure Identity dla platformy .NET:

dotnet add package Azure.Identity

Aktualizowanie kodu źródłowego w celu użycia wartości DefaultAzureCredential

Biblioteka tożsamości platformy DefaultAzureCredential Azure umożliwia uruchamianie tego samego kodu w lokalnym środowisku projektowym i w chmurze platformy Azure. Utwórz pojedyncze poświadczenie i użyj ponownie wystąpienia poświadczeń zgodnie z potrzebami, aby skorzystać z buforowania tokenów.

Aby uzyskać więcej informacji na DefaultAzureCredential temat platformy .NET, zobacz Biblioteka klienta usługi Azure Identity dla platformy .NET.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Programowanie lokalne

Programowanie lokalne przy użyciu ról obejmuje następujące kroki:

  • Przypisz tożsamość osobistą do ról RBAC w określonym zasobie.
  • Użyj narzędzia takiego jak interfejs wiersza polecenia platformy Azure lub programu Azure PowerShell do uwierzytelniania za pomocą platformy Azure.
  • Ustanów zmienne środowiskowe dla zasobu.

Role na potrzeby programowania lokalnego

Jako deweloper lokalny tożsamość platformy Azure wymaga pełnej kontroli nad operacjami płaszczyzny danych. Są to sugerowane role:

  • Współautor usługi wyszukiwania, tworzenie obiektów i zarządzanie nimi
  • Współautor danych indeksu wyszukiwania, ładowanie indeksu
  • Czytnik danych indeksu wyszukiwania, wykonywanie zapytań względem indeksu

Znajdź swoją tożsamość osobistą przy użyciu jednego z następujących narzędzi. Użyj tej tożsamości jako <identity-id> wartości.

  1. Zaloguj się do interfejsu wiersza polecenia platformy Azure.

    az login

  2. Uzyskaj tożsamość osobistą.

    az ad signed-in-user show \
    --query id -o tsv

  3. Przypisz rolę kontroli dostępu opartej na rolach (RBAC) do tożsamości grupy zasobów.

    az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

Jeśli ma to zastosowanie, zastąp <identity-id>wartości , <subscription-id>i <resource-group-name> rzeczywistymi wartościami.

Uwierzytelnianie na potrzeby programowania lokalnego

Użyj narzędzia w lokalnym środowisku projektowym, aby uwierzytelnić się w tożsamości platformy Azure. Po uwierzytelnieniu DefaultAzureCredential wystąpienie w kodzie źródłowym znajdzie i użyje uwierzytelniania.

Wybierz narzędzie do uwierzytelniania podczas programowania lokalnego.

Konfigurowanie zmiennych środowiskowych na potrzeby programowania lokalnego

Aby nawiązać połączenie z usługą Azure AI Search, kod musi znać punkt końcowy zasobu.

Utwórz zmienną środowiskową o nazwie AZURE_SEARCH_ENDPOINT dla punktu końcowego usługi Azure AI Search. Ten adres URL ma zazwyczaj format https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Obciążenia produkcyjne

Wdrażanie obciążeń produkcyjnych obejmuje następujące kroki:

  • Wybierz role RBAC, które są zgodne z zasadą najniższych uprawnień.
  • Przypisz role RBAC do tożsamości produkcyjnej dla określonego zasobu.
  • Skonfiguruj zmienne środowiskowe dla zasobu.

Role dla obciążeń produkcyjnych

Aby utworzyć zasoby produkcyjne, należy utworzyć tożsamość zarządzaną przypisaną przez użytkownika, a następnie przypisać jej tożsamość do zasobów przy użyciu odpowiednich ról.

W przypadku aplikacji produkcyjnej sugerowana jest następująca rola:

Nazwa roli Id
Czytnik danych indeksu wyszukiwania 1407120a-92aa-4202-b7e9-c0e197c71c8f

Uwierzytelnianie dla obciążeń produkcyjnych

Użyj następującego szablonu Bicep usługi Azure AI Search, aby utworzyć zasób i ustawić uwierzytelnianie dla elementu identityId. Bicep wymaga identyfikatora roli. Pokazany name w tym fragmencie kodu Bicep nie jest rolą platformy Azure— jest specyficzny dla wdrożenia Bicep.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

Plik main.bicep wywołuje następujący ogólny kod Bicep, aby utworzyć dowolną rolę. Istnieje możliwość utworzenia wielu ról RBAC, takich jak jedna dla użytkownika, a druga dla środowiska produkcyjnego. Dzięki temu można włączyć zarówno środowiska programistyczne, jak i produkcyjne w ramach tego samego wdrożenia Bicep.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Konfigurowanie zmiennych środowiskowych dla obciążeń produkcyjnych

Aby nawiązać połączenie z usługą Azure AI Search, kod musi znać punkt końcowy zasobu i identyfikator tożsamości zarządzanej.

Utwórz zmienne środowiskowe dla wdrożonego i bez klucza zasobu usługi Azure AI Search:

  • AZURE_SEARCH_ENDPOINT: ten adres URL jest punktem dostępu dla zasobu usługi Azure AI Search. Ten adres URL ma zazwyczaj format https://<YOUR-RESOURCE-NAME>.search.windows.net/.
  • AZURE_CLIENT_ID: jest to tożsamość do uwierzytelnienia jako.

Powiązana zawartość