キー認証を使用して Azure AI Search に接続する
Azure AI Search には、検索サービスへの接続で使用できるキーベースの認証が用意されています。 API キーは、ランダムに生成された 52 個の数字と文字から成る一意の文字列です。 検索サービス エンドポイントに対して行われた要求は、要求と API キーの両方が有効な場合に受け入れられます。
Note
Azure AI Search での 「キー」用語の使用方法に関する簡単な注意事項。 この記事で記述されている "API キー" は、要求の認証に使用される GUID を指します。 別の用語 "ドキュメント キー" は、検索インデックス内のドキュメントを一意に識別するために使用される、インデックス付きコンテンツ内の一意の文字列を指します。
API キーの種類
要求の認証には、次の 2 種類のキーが使用されます。
| Type | アクセス許可レベル | 最大値 | 作成方法 |
|---|---|---|---|
| [Admin] | すべてのコンテンツ操作に対するフル アクセス (読み取り/書き込み) | 2 1 | プライマリ キーおよびセカンダリ キーと呼ばれる、ポータルの 2 つの管理者キーは、サービスの作成時に生成され、要求に応じて個別に再生成できます。 |
| クエリ | 検索インデックスのドキュメント コレクションを対象とした読み取り専用アクセス | 50 | サービスで 1 つのクエリ キーが生成されます。 検索サービス管理者は、さらに必要に応じて作成できます。 |
1 2 つあることで、サービスへの継続的なアクセスに 1 つのキーを使用している間に、もう 1 つのキーをロールオーバーできます。
管理者キーとクエリ キーに見た目の違いはありません。 どちらのキーも、ランダムに生成された 52 個の英数字からなる文字列です。 アプリケーションで指定されているキーの種類がわからなくなった場合、ポータルでキーの値を確認できます。
接続で API キーを使用する
API キーは、Search REST API で表されるインデックスやその他の要求の作成やアクセスなど、データ プレーン (コンテンツ) 要求に使用されます。 サービスの作成時に、API キーはデータ プレーン操作の唯一の認証メカニズムですが、コードでハードコーディングされたキーを使用できない場合は、キー認証を Azure ロールで置き換えたり補完したりできます。
API キーは、検索サービスへのクライアント要求で指定されます。 要求に有効な API キーを渡すことは、その要求が承認済みクライアントからのものであることの証明と見なされます。 オブジェクトを作成、変更、または削除する場合は、管理者 API キーが必要です。 それ以外の場合は、通常、クエリを発行するクライアント アプリケーションにクエリ キーが配布されます。
REST API 呼び出しの要求ヘッダー、または Azure SDK で azure.search.documents クライアント ライブラリを呼び出すコードで、API キーを指定できます。 Azure portal を使用してタスクを実行している場合、ロールの割り当てによってアクセスのレベルが決まります。
ソース ファイルでハードコーディングされたキーを使用するためのベスト プラクティスは次のとおりです。
データ漏えいのリスクがない (サンプル データを使用する場合など) 場合や、ファイアウォールの背後で操作している場合にのみ、API キーを使用します。 API キーを公開すると、データと検索サービスの不正使用の両方のリスクがあります。
コード、サンプル、トレーニング資料は公開前に必ず確認し、有効な API キーを残さないようにします。
運用ワークロードの場合、Microsoft Entra ID とロールベースのアクセスに切り替えます。 または、API キーを引き続き使用する場合は、API キーにアクセスできるユーザーを常に監視し、定期的に API キーを再生成してください。
Azure portal における API キーの使用方法:
- キー認証が組み込まれています。 既定では、このポータルでは最初に API キーが試行されます。 ただし、API キーを無効にしてロールの割り当てを設定した場合、ポータルでは代わりにロールの割り当てが使用されます。
API キーを表示または管理するためのアクセス許可
API キーを表示および管理するためのアクセス許可は、ロールの割り当てによって伝達されます。 次のロールのメンバーは、キーの表示と再生成が可能です:
- [所有者]
- Contributor
- Search Service Contributor
- 管理者と共同管理者 (クラシック)
次のロールは API キーにアクセスできません。
- 閲覧者
- 検索インデックス データ共同作成者
- 検索インデックス データ閲覧者
既存のキーを見つける
API キーを表示および管理するには、Azure portal を使用するか、PowerShell、Azure CLI、または REST API 経由で行います。
Azure portal にサインインし、ご利用の検索サービスを探します。
[設定] で [キー] を選択して、管理者キーとクエリ キーを表示します。
クエリ キーを作成する
クエリ キーは、ドキュメント コレクションをターゲットとする操作のために、インデックス内のドキュメントへの読み取り専用アクセスに使用されます。 検索、フィルター、および推奨クエリは、いずれもクエリ キーを取得する操作です。 インデックス定義やインデクサーの状態など、システム データまたはオブジェクト定義を返す読み取り専用操作には、管理者キーが必要です。
クライアント アプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。 クライアント アプリから発信されたクエリには、常に管理者キーではなくクエリ キーを使用します。
Azure portal にサインインし、ご利用の検索サービスを探します。
[設定]で [キー] 選択して、API キーを表示します。
[クエリ キーの管理] で、サービス用に既に生成されているクエリ キーを使用するか、新しいクエリ キーを作成します。 既定のクエリ キーには名前はありませんが、生成された他のクエリ キーには、管理を容易にするために名前を付けることができます。
管理者キーを再生成する
ビジネス継続性のためにセカンダリ キーを使用しているときに、プライマリ キーをローテーションできるように、サービスごとに 2 つの管理者キーが作成されます。
[設定]で [キー] 選択し、セカンダリ キーをコピーします。
すべてのアプリケーションについて、セカンダリ キーを使用するように API キーの設定を更新します。
プライマリ キーを再生成します。
新しいプライマリ キーを使用するように、すべてのアプリケーションを更新します。
誤って両方のキーを同時に再生成すると、それらのキーを使用するすべてのクライアント要求が HTTP 403 Forbidden で失敗します。 ただし、コンテンツは削除されず、永続的にロックアウトされることはありません。
引き続き、ポータルまたはプログラムを使用してサービスにアクセスできます。 管理機能は、サービス API キーではなくサブスクリプション ID を使用して操作するため、自分の API キーがない場合でも使用できます。
ポータルまたは管理レイヤーを介して新しいキーを作成した後に、要求時にそのキーを指定すると、アクセスがコンテンツ (インデックス、インデクサー、データ ソース、シノニム マップ) に復元されます。
API キーをセキュリティ保護する
ロールの割り当てを使用して、API キーへのアクセスを制限します。
カスタマー マネージド キー暗号化を使用して API キーを暗号化することはできません。 CMK で暗号化できるのは、検索サービス自体内の機密データ (データ ソース オブジェクト定義のインデックス コンテンツや接続文字列など) のみです。
Azure portal で検索サービス ページを開きます。
左のナビゲーション ペインで、[アクセス制御 (IAM)] を選択し、[ロールの割り当て] タブを選択します。
[ロール] フィルターで、キーを表示または管理するアクセス許可を持つロール (所有者、共同作成者、Search Service 共同作成者) を選択します。 これらのロールに割り当てられた結果のセキュリティ プリンシパルは、検索サービスに対するキーのアクセス許可を持ちます。
予防措置として、[クラシック管理者] タブを確認して、管理者と共同管理者がアクセス権を持っているかどうかを確認します。