ロールを使用して Azure AI 検索に接続する

Azure には、プラットフォームで実行されるすべてのサービスに対し、グローバルな認証とロールベースの承認システムが用意されています。 Azure AI Search では、次の目的で Azure ロールを割り当てることができます。

検索結果に対するユーザーごとのアクセス ("行レベル セキュリティ" または "ドキュメントレベル セキュリティ" と呼ばれることもあります) は、ロールの割り当てではサポートされていません。 回避策としては、[セキュリティ フィルターの作成] を使用してユーザー ID 別に結果を整理し、要求者がアクセスしてはならないドキュメントを削除します。 デモについては、こちらの「RAG を使用したエンタープライズ チャット サンプル」を参照してください。

ロールの割り当ては、すべてのツールとクライアント ライブラリ全体に累積され、広く適用されます。 ロールは、Azure のロールベースのアクセス制御のドキュメントで説明されている、サポートされている方法のいずれかを使用して割り当てることができます。

ロールベースのアクセスはオプションですが、使用することをお勧めします。 代替策としてはキーベースの認証があり、こちらは既定のものです。

前提条件

次のロールが組み込まれています。 これらのロールが不十分な場合は、カスタム ロールを作成します。

役割 プレーン 説明
所有者 コントロールとデータ Azure ロールを割り当てる機能を含む、検索リソースのコントロール プレーンへのフル アクセス。 所有者ロールだけが、認証オプションを有効または無効にしたり、他のユーザーのロールを管理したりできます。 サブスクリプション管理者は既定でメンバーになります。

データ プレーンでは、このロールには、Search サービス共同作成者ロールと同じアクセス権があります。 これには、検索インデックスまたはインデックス ドキュメントのクエリを実行する機能を除く、すべてのデータ プレーン アクションへのアクセス権が含まれます。
Contributor コントロールとデータ ロールの割り当て、認証オプションの変更を除いて、所有者と同じコントロール プレーン アクセス レベル。

データ プレーンでは、このロールには、Search サービス共同作成者ロールと同じアクセス権があります。 これには、検索インデックスまたはインデックス ドキュメントのクエリを実行する機能を除く、すべてのデータ プレーン アクションへのアクセス権が含まれます。
Reader コントロールとデータ 検索メトリック、コンテンツ メトリック (消費されたストレージ、オブジェクトの数)、データ プレーン リソース (インデックス、インデクサーなど) のオブジェクト定義など、サービス全体にわたる読み取りアクセス。 閲覧者ロールは、API キーの読み取りやインデックス内のコンテンツの読み取りには引き続きアクセスできません。
Search Service Contributor コントロールとデータ オブジェクト定義 (インデックス、別名、同意語マップ、インデクサー、データソース、スキルセット) に対する読み取り/書き込みアクセス。 このロールは、オブジェクトを作成する開発者、および検索サービスとそのオブジェクトを管理する管理者向けですが、インデックス コンテンツにはアクセスできません。 このロールを使用して、インデックスの作成、削除、一覧表示、インデックス定義の取得、サービス情報 (統計とクォータ) の取得、アナライザーのテスト、同意語マップ、インデクサー、データ ソース、スキルセットの作成と管理を行います。 アクセス許可の一覧については、「Microsoft.Search/searchServices/*」を参照してください。
検索インデックス データ共同作成者 データ​​ インデックス内のコンテンツに対する読み取り/書き込みアクセス。 このロールは、インデックスのドキュメント コレクションのインポート、更新、またはクエリを行う必要がある開発者またはインデックス所有者向けです。 このロールでは、インデックスの作成や管理はサポートしていません。 既定では、検索サービスのすべてのインデックスを対象としています。 スコープを絞り込むには、「1 つのインデックスへのアクセスを許可する」を参照してください。
検索インデックス データ閲覧者 データ​​ 検索インデックスのクエリを実行するための読み取り専用アクセス。 このロールは、クエリを実行するアプリおよびユーザー向けです。 このロールでは、オブジェクト定義への読み取りアクセスはサポートしていません。 たとえば、検索インデックス定義を読み取ったり、検索サービスの統計情報を取得したりすることはできません。 既定では、検索サービスのすべてのインデックスを対象としています。 スコープを絞り込むには、「1 つのインデックスへのアクセスを許可する」を参照してください。

これらのロールを組み合わせて、自分のユース ケースのために十分なアクセス許可を取得します。

Note

Azure ロールベースのアクセスを無効にした場合、コントロール パネルの組み込みロール (所有者、共同作成者、閲覧者) を引き続き使用できます。 ロールベースのアクセスを無効にすると、これらのロールに関連付けられたデータ関連の権限だけが削除されます。 データ プレーンのロールが無効の場合、Search サービス共同作成者はコントロール プレーンの共同作成者と同等になります。

ロールの割り当て

このセクションでは、次のロールを割り当てます。

サービス管理のロールを割り当てる

サービス管理者は、Search Service を作成して構成し、Management REST API または同等のクライアント ライブラリに記述されているすべてのコントロール プレーン操作を実行できます。 ロールによっては、ほとんどのデータ プレーンの Search REST API を実行することもできます。

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

  2. お使いの検索サービスに移動します。

  3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

  4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

  5. 該当するロールを選びます。

    • 所有者 (クエリのアクセス許可を除く、すべてのデータ プレーン操作とコントロール プレーン操作へのフル アクセス)
    • 共同作成者 (ロールを割り当てるアクセス許可を除き、所有者と同じ)
    • 閲覧者 (メトリックの監視と表示に使用可能)
  6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。

  7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

開発用のロールを割り当てる

ロールの割り当ては、Search Service 全体でグローバルに行われます。 単一のインデックスにアクセス許可のスコープ指定を行う場合は、代わりに PowerShell または Azure CLI を使用してカスタム ロールを作成します。

フル アクセスを提供するロールのもう 1 つの組み合わせは、共同作成者または所有者、および Search インデックス データ閲覧者です。

重要

サービスまたはインデックスに対してロールベースのアクセスを構成し、要求に API キーも指定した場合、Search Service では API キーを使用して認証が行われます。

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

  2. お使いの検索サービスに移動します。

  3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

  4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

    [ロールの割り当ての追加] メニューが開いている [アクセス制御 (IAM)] ページ。

  5. ロールを選択します。

    • Search Service Contributor (インデックス、インデクサー、スキルセット、その他の最上位オブジェクトに対する create-read-update-delete 操作)
    • Search インデックス データ共同作成者 (ドキュメントの読み込みとインデックス作成ジョブの実行)
    • Search インデックス データ閲覧者 (インデックスのクエリ)

    フル アクセスを提供するロールのもう 1 つの組み合わせは、共同作成者または所有者、および Search インデックス データ閲覧者です。

  6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。

  7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

  8. 他のロールに対しても繰り返します。 ほとんどの開発者には、3 つがすべて必要です。

読み取り専用クエリのロールを割り当てる

インデックスへの読み取りアクセスのみが必要なアプリとプロセスには、Search インデックス データ閲覧者ロールを使用します。

これは目的に非常に特化したロールです。 検索、オートコンプリート、検索候補のための Search インデックスのドキュメント コレクションに対する GET アクセスまたは POST アクセス を許可します。 インデックスまたはその他の最上位レベルのオブジェクトに対する GET 操作や LIST 操作、またサービス統計の GET はサポートされていません。

このセクションでは、ロールの割り当てを設定するための基本的な手順について説明し、このセクションは完全を期すために存在します。しかし、ロールベースのアクセス用にアプリを構成する際の包括的な手順については、「キー なしで Azure AI 検索を使用する」をお勧めします。

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

  2. お使いの検索サービスに移動します。

  3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

  4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

  5. Search インデックス データ閲覧者ロールを選択します。

  6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。 別のサービスのアクセス許可を設定する場合は、システム マネージド ID またはユーザー マネージド ID を使用している可能性があります。 ロールの割り当てがサービス ID 向けの場合は、そのオプションを選択します。

  7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

ロールの割り当てをテストする

クライアントを使用して、ロールの割り当てをテストします。 ロールは累積的であり、サブスクリプションまたはリソース グループ レベルにスコープを設定された継承されたロールは、リソース (Search Service) レベルでは削除も拒否もできないことに注意してください。

キーレス接続用にアプリケーションを構成し、テストする前にロールの割り当てを行います。

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

  2. お使いの検索サービスに移動します。

  3. [概要] ページで、[インデックス] タブを選択します。

    • Search サービス共同作成者は、任意のオブジェクトを表示および作成できますが、ドキュメントを読み込んだり、インデックスに対してクエリを実行したりすることはできません。 権限を確認するには、検索インデックスを作成します

    • Search インデックス データ共同作成者は、ドキュメントを読み込むことができます。 ポータルでは [データのインポート] ウィザードの外部には [ドキュメントの読み込み] オプションはありませんが、[インデクサーのリセットと実行] を行うことでドキュメントの読み込みアクセス許可を確認できます。

    • 検索インデックス データ閲覧者は、インデックスに対してクエリを実行できます。 権限を確認するには、Search エクスプローラーを使用します。 クエリを送信し、結果を表示できるようにする必要がありますが、インデックス定義を表示できたり、作成できたりする必要はありません。

現在のユーザーとしてテスト

既に検索サービスの共同作成者または所有者である場合は、Azure AI Search への認証用のユーザー ID としてベアラー トークンを提示できます。

  1. Azure CLI を使用して現在のユーザーのベアラー トークンを取得します。

    az account get-access-token --scope https://search.azure.com/.default
    

    または PowerShell を使用する方法:

    Get-AzAccessToken -ResourceUrl https://search.azure.com
    
  2. Visual Studio Code の新しいテキスト ファイルに、次の変数を貼り付けます。

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
    @index-name = PASTE-YOUR-INDEX-NAME-HERE
    @token = PASTE-YOUR-TOKEN-HERE
    
  3. アクセスを確認する要求を貼り付けて送信します。 これは hotels-quickstart インデックスに対してクエリを実行するものです。

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
      Content-type: application/json
      Authorization: Bearer {{token}}
    
        {
             "queryType": "simple",
             "search": "motel",
             "filter": "",
             "select": "HotelName,Description,Category,Tags",
             "count": true
         }
    

1 つのインデックスへのアクセスを許可する

シナリオの一部では、アプリケーションでアクセスできる範囲を単一のリソース (インデックスなど) に制限することが必要になる場合があります。

ポータルでは現在、このレベルの細分性でロールの割り当てはサポートされていませんが、 PowerShell または Azure CLI を使用して実行できます。

PowerShell では、New-AzRoleAssignment を使って、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

  1. Azure および AzureAD モジュールを読み込み、Azure アカウントに接続します。

    Import-Module -Name Az
    Import-Module -Name AzureAD
    Connect-AzAccount
    
  2. 個々のインデックスにスコープを設定したロールの割り当てを追加します。

    New-AzRoleAssignment -ObjectId <objectId> `
        -RoleDefinitionName "Search Index Data Contributor" `
        -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
    

カスタム ロールを作成する

組み込みロールに適切なアクセス許可の組み合わせがない場合は、カスタム ロールを作成して必要な操作をサポートすることができます。

この例では、検索インデックス データ閲覧者を複製し、名前でインデックスを一覧表示する権限を追加します。 通常、検索サービスのインデックスを一覧表示することは管理者の権利とされています。

次の手順は、「Azure portal を使用して Azure カスタム ロールを作成または更新する」から派生したものです。 検索サービス ページでは、既存のロールからの複製がサポートされています。

次の手順では、インデックスを名前で一覧表示する権限を追加して検索クエリの権限を増強したカスタム ロールを作成します。 通常、インデックスの一覧表示は管理者用の機能とされています。

  1. Azure portal で検索サービスに移動します。

  2. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

  3. アクション バーで、[ロール] を選択します。

  4. [検索インデックス データ閲覧者] (または別のロール) を右クリックし、[複製] を選択して [カスタム ロールを作成する] ウィザードを開きます。

  5. [基本] タブでカスタム ロールの名前 ("Search Index Data Explorer" など) を指定し、[次へ] をクリックします。

  6. [アクセス許可] タブで [アクセス許可の追加] を選択します。

  7. [アクセス許可の追加] タブで、Microsoft Search タイルを検索して選択します。

  8. カスタム ロールのアクセス許可を設定します。 ページの上部で、既定の [アクション] の選択を使用して以下を行います。

    • Microsoft.Search/operations で、[Read : List all available operations]\(読み取り: 使用可能なすべての操作を一覧表示する\) を選択します。
    • Microsoft.Search/searchServices/indexes で、[Read: Read Index]\(読み取り: インデックスの読み取り\) を選択します。
  9. 同じページの [データ アクション] に切り替え、Microsoft.Search/searchServices/indexes/documents で [Read : Read Documents]\(読み取り: ドキュメントの読み取り\) を選択します。

    JSON の定義は、次の例のようになります。

    {
     "properties": {
         "roleName": "search index data explorer",
         "description": "",
         "assignableScopes": [
             "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
         ],
         "permissions": [
             {
                 "actions": [
                     "Microsoft.Search/operations/read",
                     "Microsoft.Search/searchServices/indexes/read"
                 ],
                 "notActions": [],
                 "dataActions": [
                     "Microsoft.Search/searchServices/indexes/documents/read"
                 ],
                 "notDataActions": []
             }
         ]
       }
     }
    
  10. [確認および作成] を選択してロールを作成します。 これで、ユーザーとグループをロールに割り当てることがきるようになりました。

条件付きアクセス

多要素認証などの組織のポリシーを適用する必要がある場合、Microsoft Entra 条件付きアクセスを推奨します。

Azure AI Search の条件付きアクセス ポリシーを有効にするには、次の手順を実行します。

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

  2. Microsoft Entra 条件付きアクセスを検索します。

  3. [ポリシー] を選択します。

  4. [新しいポリシー] を選択します。

  5. ポリシーの [クラウド アプリまたは操作] セクションで、ポリシーの設定方法に応じて、クラウド アプリとして Azure AI Search を追加します。

  6. ポリシーの残りのパラメーターを更新します。 たとえば、このポリシーを適用するユーザーとグループを指定します。

  7. ポリシーを保存します。

重要

検索サービスにマネージド ID が割り当てられている場合、その検索サービスは、条件付きアクセス ポリシーの一部として含めたり、除外したりすることができるクラウド アプリとして表示されます。 条件付きアクセス ポリシーを特定の検索サービスに適用することはできません。 代わりに、一般的な Azure AI Search クラウド アプリを選択してください。

制限事項

  • ロールベースのアクセス制御では、一部の要求の待機時間が長くなる可能性があります。 サービス リソース (インデックス、インデクサーなど) とサービス プリンシパルの一意の組み合わせごとに、認可チェックがトリガーされます。 これらの認可チェックにより、要求あたり最大 200 ミリ秒の待機時間が追加される可能性があります。

  • まれに、多数の異なるサービス プリンシパルから要求が送信され、すべてが異なるサービス リソース (インデックス、インデクサーなど) を対象としている場合、認可チェックによって調整が発生する可能性があります。 調整が発生するのは、検索サービス リソースとサービス プリンシパルの一意の組み合わせが 1 秒間に何百も使われた場合のみです。

ロール ベースの Access Control の問題のトラブルシューティング

認証にロールベースのアクセス制御を使用するアプリケーションを開発する場合、いくつかの一般的な問題が発生する可能性があります。

  • 承認トークンがマネージド ID から取得され、適切なアクセス許可が最近割り当てられた場合、これらのアクセス許可の割り当てが有効になるには、数時間かかる場合があります。

  • Search Service の既定の構成は、キーベースの認証です。 既定のキー設定を [両方] または [ロールベースのアクセス制御] に変更しなかった場合、基になるアクセス許可に関係なく、ロールベースの認証を使用するすべての要求が自動的に拒否されます。