キーなしで Azure AI 検索を使用する

[アーティクル]
10/16/2024

アプリケーションコードでは、認証と認可に Microsoft Entra ID とロールを使用するキーレス接続を Azure AI 検索に対して設定できます。ほとんどの Azure サービスへのアプリケーション要求は、キーまたはキーレス接続を使って認証する必要があります。開発者は、安全でない場所にアクセス・キーを公開しないよう注意する必要があります。このキーへのアクセス権を取得したユーザーは誰でもサービスの認証を受けることができます。キーレス認証の場合、キー (または接続文字列) を保存する必要がないため、アカウントキーよりも管理とセキュリティの面で利点があります。

キーレス接続を有効にするには、次の手順を実行します。

認証を構成します。
必要に応じて、環境変数を設定します。
Azure ID ライブラリの資格情報の種類を使用して、Azure AI 検索クライアントオブジェクトを作成します。

前提条件

ローカル開発と運用の両ワークロードで次の手順を完了する必要があります。

AI 検索リソースを作成する

この記事を続ける前に、使用できる Azure AI 検索リソースが必要です。リソースがない場合は、今すぐリソースを作成してください。リソースのロールベースのアクセス制御 (RBAC) を有効にします。

Azure ID クライアントライブラリのインストール

キーレスを使わずにローカルで作業する前に、Azure ID クライアントライブラリを使用して AI 検索を有効にしたコードを更新します。

.NET 用 Azure ID クライアントライブラリをインストールします。

dotnet add package Azure.Identity

次の POM ファイルを使用して Java 用 Azure ID クライアントライブラリをインストールします。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript 用 Azure ID クライアントライブラリをインストールします。

npm install --save @azure/identity

Python 用 Azure ID クライアントライブラリをインストールします。

pip install azure-identity

DefaultAzureCredential を使用するようにソースコードを更新する

Azure ID ライブラリの DefaultAzureCredential を使用すると、ローカル開発環境と Azure クラウドで同じコードを実行できます。 1 つの資格情報を作成し、必要に応じてその資格情報インスタンスを再利用して、トークンのキャッシュを利用します。

.NET 用の DefaultAzureCredential について詳しくは、「.NET 用 Azure ID クライアントライブラリ」をご覧ください。

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);

Java 用の DefaultAzureCredential について詳しくは、「Java 用 Azure ID クライアントライブラリ」をご覧ください。

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

JavaScript 用の DefaultAzureCredential について詳しくは、「JavaScript 用 Azure ID クライアントライブラリ」をご覧ください。

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

Python 用の DefaultAzureCredential について詳しくは、「Python 用 Azure ID クライアントライブラリ」をご覧ください。

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.windows.net"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

ローカル開発

キーレスを使わないローカル開発には、次の手順が含まれます。

特定のリソースに対して RBAC ロールを使用して個人 ID を割り当てます。
ツールを使用して Azure の認証を受けます。
リソースの環境変数を設定します。

ローカル開発のロール

ローカル開発者である場合、お使いの Azure ID でサービスを完全に制御できる必要があります。この制御は RBAC ロールで提供されます。開発中にリソースを管理するには、次のロールが推奨されます。

Search Service Contributor
検索インデックスデータ共同作成者
検索インデックスデータ閲覧者

次のツールのいずれかを使用して、個人の ID を確認します。その ID を <identity-id> 値として使用します。

Azure CLI にサインインします。
```
az login
```

個人の ID を取得します。

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

リソースグループの ID にロールベースのアクセス制御 (RBAC) ロールを割り当てます。

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

PowerShell を使用してサインインします。
```
Connect-AzAccount
```

個人の ID を取得します。

(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]

リソースグループの ID にロールベースのアクセス制御 (RBAC) ロールを割り当てます。

New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

該当する場合、<identity-id>、<subscription-id>、<resource-group-name> を実際の値に置き換えます。

ローカル開発の認証

ローカル開発環境でツールを使用して、Azure ID に対する認証を行います。認証されると、ソースコード内の DefaultAzureCredential インスタンスによって認証が検出され、使用されます。

ローカル開発時に認証用のツールを選択します。

ローカル開発の環境変数を構成する

Azure AI 検索に接続するには、コードがリソースエンドポイントを認識している必要があります。

Azure AI 検索エンドポイント用に AZURE_SEARCH_ENDPOINT という環境変数を作成します。通常、この URL の形式は https://<YOUR-RESOURCE-NAME>.search.windows.net/ です。

運用ワークロード

運用ワークロードのデプロイには次の手順が含まれます。

最小限の特権の原則に従う RBAC ロールを選択します。
特定のリソース上の運用 ID に RBAC ロールを割り当てます。
リソースの環境変数を設定します。

運用ワークロードのロール

運用リソースを作成するには、ユーザー割り当てマネージド ID を作成し、その ID を正しいロールを持つリソースに割り当てる必要があります。

運用アプリケーションには次のロールが推奨されます。

ロール名	Id
検索インデックスデータ閲覧者	1407120a-92aa-4202-b7e9-c0e197c71c8f

運用ワークロードの認証

次の Azure AI 検索 Bicep テンプレートを使用してリソースを作成し、identityId の認証を設定します。 Bicep には、ロール ID が必要です。この Bicep スニペットに示されている name は Azure ロールではありません。これは 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
    }
}

main.bicep ファイルにより、次の汎用 Bicep コードが呼び出され、ロールが作成されます。ユーザー用と運用用など、複数の RBAC ロールを作成することもできます。こうすると、同じ 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)
    }
}

運用ワークロードの環境変数を構成する

Azure AI 検索に接続するには、リソースエンドポイントと、マネージド ID の ID をコードが認識している必要があります。

デプロイされたキーレス Azure AI 検索リソースの環境変数を作成します。

AZURE_SEARCH_ENDPOINT: この URL は、Azure AI 検索リソースのアクセスポイントです。通常、この URL の形式は https://<YOUR-RESOURCE-NAME>.search.windows.net/ です。
AZURE_CLIENT_ID: これは認証する ID です。

次の方法で共有

キーなしで Azure AI 検索を使用する

前提条件

AI 検索リソースを作成する

Azure ID クライアントライブラリのインストール

DefaultAzureCredential を使用するようにソースコードを更新する

ローカル開発

ローカル開発のロール

ローカル開発の認証

ローカル開発の環境変数を構成する

運用ワークロード

運用ワークロードのロール

運用ワークロードの認証

運用ワークロードの環境変数を構成する

フィードバック

その他のリソース

次の方法で共有

キーなしで Azure AI 検索を使用する

前提条件

AI 検索リソースを作成する

Azure ID クライアント ライブラリのインストール

DefaultAzureCredential を使用するようにソース コードを更新する

ローカル開発

ローカル開発のロール

ローカル開発の認証

ローカル開発の環境変数を構成する

運用ワークロード

運用ワークロードのロール

運用ワークロードの認証

運用ワークロードの環境変数を構成する

関連するコンテンツ

フィードバック

その他のリソース

Azure ID クライアントライブラリのインストール

DefaultAzureCredential を使用するようにソースコードを更新する