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

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

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

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

前提条件

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

• AI 検索リソースを作成する
• 検索サービスでロールベースのアクセスを有効にする
• Azure ID クライアント ライブラリをインストールする

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

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

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

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

.NET

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

dotnet add package Azure.Identity

Java

次の 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

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

npm install --save @azure/identity

Python

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

pip install azure-identity

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

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

.NET

.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

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

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

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

1. Azure CLI にサインインします。

   az login
   

2. 個人の ID を取得します。

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

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

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

Azure PowerShell

1. PowerShell を使用してサインインします。

   Connect-AzAccount
   

2. 個人の ID を取得します。

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

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

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

Azure Portal

1. 次のステップを使用します。Azure portal でユーザー オブジェクト ID を 見つけます。

2. Azure portal で、[ロールの割り当ての追加] を開くページにあるステップを使用します。

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

ローカル開発の認証

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

.NET

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

Java

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

JavaScript

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

Python

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

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

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 組み込みロール