Azure ロールベースのアクセス制御 (Azure RBAC) を使用して Azure AI Search に接続する

Azure には、プラットフォームで実行されるすべてのサービスに対し、グローバルなロールベースのアクセス制御承認システムが用意されています。 Azure AI Search では、次の用途に Azure ロールを使用できます。

  • コントロール プレーン操作 (Azure Resource Manager によるサービス管理タスク)。

  • インデックスの作成、読込、クエリなどのデータ プレーン操作。

検索結果に対するユーザー アクセスごとに (行レベル セキュリティまたはドキュメントレベル セキュリティと呼ばれることもあります) はサポートされていません。 回避策としては、[セキュリティ フィルターの作成] を使用してユーザー ID 別に結果を整理し、要求者がアクセスしてはならないドキュメントを削除します。

Note

Azure AI Search では、"コントロール プレーン" は、Management REST API または同等のクライアント ライブラリでサポートされる操作を意味します。 "データ プレーン" は、インデックス作成やクエリなどの検索サービス エンドポイントに対する操作、または Search REST API または同等のクライアント ライブラリで指定されるその他の操作を意味します。

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

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

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

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

Note

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

制限事項

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

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

データ プレーンにロールベースのアクセスを構成する

適用対象: Search インデックス データ共同作成者、Search インデックス データ閲覧者、Search サービス共同作成者

この手順では、OAuth2 アクセス トークンを提供するデータ要求の承認ヘッダーを認識するように検索サービスを構成します。

  1. Azure portal にサインインし、検索サービス ページを開きます。

  2. 左側のナビゲーション ペインで [キー] を選択します。

    認証オプションを含むキー ページのスクリーンショット。

  3. [API アクセス制御] オプションを選択します。 柔軟性を求める場合、あるいはアプリを移行する必要がある場合、[両方] をお勧めします。

    オプション 説明
    API キー (既定) 承認するには、要求ヘッダーに管理者またはクエリの API キーが必要です。 ロールは使用されません。
    ロールベースのアクセス制御 次のステップで説明するように、タスクを完了するには、ロール割り当てのメンバーシップが必要です。 また、Authorization ヘッダーも必要です。
    両方 API キーまたはロールベースのアクセス制御のいずれかを使用する要求が有効です。

変更はすぐに有効になりますが、テストする前に数秒待ってください。

検索サービス操作とコンテンツに対するすべてのネットワーク呼び出しでは、選択したオプション (API キー、ベアラー トークン、または [両方] を選択した場合はいずれか) が優先されます。

ポータルでロールベースのアクセス制御を有効にすると、認証に失敗したとき、失敗モードが "http401WithBearerChallenge" になります。

ロールの割り当て

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

ロールの割り当てを管理するには、所有者であるか、Microsoft.Authorization/roleAssignments/write アクセス許可を持っている必要があります。

ポータルでのロールの割り当ては、サービス全体です。 単一のインデックスにアクセス許可を付与する場合は、代わりに PowerShell または Azure CLI を使用します。

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

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

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

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

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

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

    • [所有者]
    • Contributor
    • Reader
    • Search Service Contributor
    • 検索インデックス データ共同作成者
    • 検索インデックス データ閲覧者
  6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。

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

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

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

アクセスをテストする前に、Microsoft Entra ID にクライアント アプリケーションを登録し、ロールの割り当てを終えていることを確認します。

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

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

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

    • 共同作成者は、任意のオブジェクトを表示および作成できますが、検索エクスプローラーを使用してインデックスに対してクエリを実行することはできません。

    • Search インデックス データ閲覧者は、Search エクスプローラーを使用してインデックスのクエリを実行できます。 任意の API バージョンを使用して、アクセスを確認できます。 クエリを送信し、結果を表示できるようにする必要がありますが、インデックス定義を表示できる必要はありません。

    • 検索インデックス データ共同作成者は、[新しいインデックス] を選択して、新しいインデックスを作成できます。 新しいインデックスを保存すると、サービスに対する書き込みアクセス権が検証されます。

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

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

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

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

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

    Get-AzAccessToken -ResourceUrl "https://graph.microsoft.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=2023-11-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/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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. [確認および作成] を選択してロールを作成します。 これで、ユーザーとグループをロールに割り当てることがきるようになりました。

API キー認証を無効にする

キー アクセス、またはローカル認証は、検索サービス共同作成者、検索インデックス データ共同作成者、検索インデックス データ閲覧者の各ロールと、Microsoft Entra 認証を使用している場合は、サービスで無効にできます。 API キーを無効にすると、ヘッダーで API キーを渡すデータ関連のすべての要求を検索サービスが拒否します。

Note

管理者 API キーは無効にできるだけで、削除できません。 クエリ API キーは削除できます。

機能を無効にするには、所有者または共同作成者のアクセス許可が必要です。

キーベースの認証を無効にするには、Azure portal または Management REST API を使用します。

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

  2. 左側のナビゲーション ウィンドウで、[キー] を選択します。

  3. [ロールベースのアクセス制御] を選択します。

変更はすぐに有効になりますが、テストする前に数秒待ってください。 所有者、サービス管理者、または共同管理者のメンバーとしてロールを割り当てるアクセス許可があると仮定すると、ポータル機能を使用してロールベースのアクセスをテストできます。

条件付きアクセス

条件付きアクセスは、組織のポリシーを適用するために Microsoft Entra ID で使われるツールです。 条件付きアクセス ポリシーを使用すると、必要な場合は適切なアクセス制御を適用して組織のセキュリティを維持することができます。 ロールベースのアクセス制御を使用して Azure AI Search サービスにアクセスすると、条件付きアクセスにより、組織ポリシーを適用することができます。

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

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

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

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

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

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

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

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

重要

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

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

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

  • 承認トークンがマネージド ID から取得され、適切なアクセス許可が最近割り当てられた場合、これらのアクセス許可の割り当てが有効になるには、数時間かかる場合があります。
  • 検索サービスの既定の構成は、キーベースの認証のみです。 既定のキー設定を [両方] または [ロールベースのアクセス制御] に変更しなかった場合、基になるアクセス許可に関係なく、ロールベースの認証を使用するすべての要求が自動的に拒否されます。