Azure AI 検索でのクエリ時間 ACL と RBAC の適用 (プレビュー)

クエリ時間アクセス制御 (プレビュー) を使用すると、ユーザーは ID、グループ メンバーシップ、ロール、または属性に基づいて、アクセスが許可されている検索結果のみを取得できます。 この機能は、セキュリティで保護されたエンタープライズ検索とコンプライアンスに基づくワークフローに不可欠です。

承認されたアクセスは、インデックス作成中に取り込まれるアクセス許可メタデータによって異なります。 Azure Data Lake Storage (ADLS) Gen2 や Microsoft 365 のSharePointなど、組み込みのアクセス モデルを持つインデクサー データ ソースの場合、インデクサーは各ドキュメントのアクセス許可メタデータを自動的にプルできます。 他のデータ ソースの場合は、ドキュメント ペイロードを自分でアセンブルする必要があり、ペイロードにはコンテンツと関連するアクセス許可メタデータの両方が含まれている必要があります。 その後、 プッシュ API を 使用してインデックスを読み込みます。

この記事では、アクセス許可メタデータを使用して結果をフィルター処理するクエリを設定する方法について説明します。

前提 条件

• アクセス許可メタデータは、 filterable 文字列フィールドに含まれる必要があります。 クエリではフィルターを使用しませんが、検索エンジンによって内部的にフィルターが作成され、承認されていないコンテンツが除外されます。

• アクセス許可メタデータは、アクセス レベルとグループまたはユーザー ID を識別する POSIX スタイルのアクセス許可、または RBAC スコープを使用している場合は ADLS Gen2 のコンテナーのリソース ID で構成されている必要があります。

• カスタム インジェストで ACL ベースの適用を行う場合は、フィルター可能なフィールドにuserIdsとgroupIdsをMicrosoft Entraオブジェクト ID (GUID) として格納します。 クエリ時に、サービスは、 x-ms-query-source-authorization 内の ID を格納されている ID と照合します。 スキーマの詳細については、 プッシュ REST API (プレビュー) を使用したドキュメント アクセス制御リスト (ACL) のインデックス作成に関するページを参照してください。

• データ ソースによって異なります。

  • ADLS Gen2 データ ソースの場合、コンテナー レベルでアクセス制御リスト (ACL) と/または Azure ロールベースのアクセス制御 (RBAC) のロールを構成しておく必要があります。
  • Azure BLOB データ ソースの場合は、コンテナーにロールの割り当てが必要です。 組み込みのインデクサー、ナレッジ ソース、またはプッシュ API を使用して、インデックス内のアクセス許可メタデータにインデックスを作成できます。
  • SharePointデータ ソースの場合は、アクセス制御リスト (ACL) を構成する必要があります。 組み込みの SharePointインデクサーを使用し、ACL インジェスト機能で構成できます。 また、インデックス付きのSharePointナレッジ ソースを使用して、ドキュメント レベルのアクセス許可を適用するように構成することもできます。 Microsoft 365 グループを含むグループベースのアクセス許可は、Entra オブジェクト ID として取り込まれるときにサポートされます。 グループの拡張は、クエリ時にMicrosoft Graphによって行われます。

• 最新のプレビュー REST API またはAzure SDKのプレビュー パッケージを使用して、インデックスまたはナレッジ ソースに対してクエリを実行します。 この API バージョンでは、承認されていない結果を除外する内部クエリがサポートされています。

制限

• ACL の評価が失敗した場合 (たとえば、Graph APIが使用できない場合)、サービスは 5xx を返しnot部分的にフィルター処理された結果セットを返します。

• ACL の鮮度はインジェスト方法によって異なります。 古い承認の決定を回避するには、各ソースがアクセス許可の変更をインデックスに反映する方法を計画します。

  • スケジュールされたSharePointインデクサーは、実行ごとに項目レベルのアクセス許可の変更を更新します。 子アイテムによって継承される親スコープ (サイト、ライブラリ、リスト、またはフォルダー) を変更するには、再同期が必要です。
  • ADLS Gen2 インデクサーでは、ACL を更新するために再同期が必要です。
  • カスタム インジェストまたはプッシュ インジェストでは、影響を受けるドキュメントを再び使用する必要があります。

• ドキュメントの表示には、次の両方が必要です。

  • 呼び出し元のアプリケーションの RBAC ロール (Authorization ヘッダー)。
  • x-ms-query-source-authorization によって伝達されるユーザー ID。

• 最初の ACL ベースのクエリでは、キャッシュとアクセス許可の解決のオーバーヘッドにより、後続の要求と比較して待機時間が長くなる可能性があります。

• インデックス付けされた SharePoint コンテンツでは、SharePoint グループ内にネストされている Microsoft Entra グループは展開されません。 Microsoft Entra の推移的なグループ解決では、この混合関係はサポートされていません。 サポートされているグループリレーションシップを参照してください。

データ ソースあたりの ACL エントリの制限

アクセス制御リスト (ACL) エントリの制限により、接続されたデータ ソース内のファイル、フォルダー、またはアイテムに関連付けることができる個別のアクセス許可レコードの数が定義されます。 各エントリは、1 つのユーザーまたはグループ ID と、その ID に付与されたアクセス権 (読み取り、書き込み、実行など) を表します。

Azure AI 検索機能でサポートされる ACL エントリの最大数は、データ ソースの種類によって異なります。

Azure Data Lake Storage Gen2 (ADLS Gen2): 各ファイルまたはディレクトリは、最大で 32 ACL エントリのアクセス許可を持つことができます。 このコンテキストでは、エントリは、特定のアクセス許可セットを持つ 1 つのプリンシパル (ユーザーまたはグループ) を意味します。 例: "Everyone" 読み取りアクセス権と "Azure ユーザー" 実行アクセスを割り当てると、2 つの ACL エントリとしてカウントされます。

Microsoft 365のSharePoint: 検索SharePointデータ ソースでは、ファイルあたり最大 1,000 個のアクセス許可エントリがサポートされます。 各エントリは、アイテムのアクセス許可リスト内の一意のユーザーまたはグループの割り当てを表します。 これは、 一意のアクセス許可 を持つ項目の数を制御する、リストまたはライブラリごとの全体的な一意のアクセス許可スコープの制限とは異なります。

これらの制限により、検索結果のインデックス作成またはフィルター処理時に、項目レベルのアクセス許可をAzure AI 検索にきめ細かく受け入れる方法が決まります。 項目がこれらの ACL エントリの制限を超えた場合、クエリ時に制限を超えるアクセス許可が適用されない可能性があります。

クエリ時の適用のしくみ

このセクションでは、クエリ時の ACL 適用の操作の順序を示します。 操作は、AZURE RBAC スコープを使用するか、グループ ID またはユーザー ID Microsoft Entra ID使用するかによって異なります。

1. ユーザーのアクセス許可の入力

エンド ユーザー アプリケーションには、検索クエリ要求の一部としてクエリ アクセス トークンが含まれており、通常、そのアクセス トークンはユーザーの ID です。 次の表に、ACL 適用のためにAzure AI 検索でサポートされているユーザーアクセス許可のソースを示します。

2. セキュリティフィルターの構築

内部的には、Azure AI 検索は、提供されたユーザーのアクセス許可に基づいてセキュリティ フィルターを動的に構築します。 これらのセキュリティ フィルターは、インデックスにアクセス許可フィルター オプションが有効になっている場合にクエリに含まれる可能性があるフィルターに自動的に追加されます。

Azure RBAC の場合、アクセス許可はリソース ID 文字列の一覧です。 承認ヘッダーのセキュリティ プリンシパル トークンへのアクセスを許可するAzure ロールの割り当て (ストレージ BLOB データ閲覧者) がデータ ソースに存在する必要があります。 リクエストでアクセス トークンを持つプリンシパルにロールの割り当てがない場合、フィルターはドキュメントを除外します。

3. 結果のフィルター処理

セキュリティ フィルターは、検索インデックス内のすべてのドキュメントの ACL の各リストに対して、要求の userIds、groupIds、rbacScope を効率的に照合し、ユーザーがアクセスできる結果に返される結果を制限します。 各フィルターは個別に適用され、フィルターが成功した場合はドキュメントが承認されたと見なされることに注意してください。 たとえば、ユーザーが userId を介してドキュメントにアクセスできるが、groupId を介してアクセスできない場合、ドキュメントは引き続き有効と見なされ、ユーザーに返されます。

クエリ時の SharePoint グループ

2026-05-01-preview REST API 以降では、Azure AI 検索は、所有者、メンバー、閲覧者、カスタム サイト グループなどのSharePointサイト グループ メンバーシップをクエリ時に受け入れることができます。 このシナリオを有効にするには、インデックスに次のものが含まれている必要があります。

• ユーザーの代わりにSharePointを呼び出すために使用されるMicrosoft Entra アプリケーションのフェデレーション ID 資格情報を参照するsharePointConnectorAppRegistration プロパティ。
• sharepointSiteUrl: true 属性でマークされたフィールド。インデックスが作成された各アイテムのSharePoint サイト URL を格納します (通常は SharePointSiteUrl という名前で、metadata_spo_site_url ソース フィールドから設定されます)。

クエリ時に、Azure AI 検索は登録されたアプリケーションと各候補ドキュメントのサイト URL を使用して、そのサイトの呼び出し元ユーザーのSharePoint グループメンバーシップを解決します。 解決されたグループは、spg:アクセス許可フィルター フィールドに格納されているgroupIdsプレフィックス付きの値と照合されます。 spg: プレフィックスは、SharePoint サイト グループと、プレフィックスなしで格納されるグループ オブジェクト ID Microsoft Entra区別します。

構成の詳細と制限事項については、構成SharePoint グループのサポートを参照してください。

SharePointアクセス許可のフィルター処理で不足または予期しない結果が返される場合は、「SharePointアクセス許可のフィルター処理のトラブルシューティング」を参照してください。

例: SharePoint サイト グループの適用を使用したクエリ

要求は、標準の ACL によって適用されるクエリと同じです。 検索サービスは、インデックスの sharePointConnectorAppRegistration を使用して、呼び出し元の代わりにSharePoint グループメンバーシップを解決します。 レスポンスでGroupIdsで始まる値を表示するには、select句にspg:を含めます。

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

クエリの例

次に、サンプル コードからのクエリ要求の例を示します。 クエリ トークンは、クエリを実行するユーザーのMicrosoft Entraアクセス トークンです。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

正しくない結果を調査するための昇格されたアクセス許可 (プレビュー)

検索結果は各ユーザーに固有であるため、アクセス許可メタデータを含むクエリのデバッグは問題になる可能性があります。 承認されていないコンテンツを返すクエリに関する問題を調査できるように、権限メタデータに関係なく結果を返すには、開発者または管理者が昇格されたアクセス許可が必要になる場合があります。

調査するには、次のことが可能である必要があります。

• エンド ユーザーがそのユーザーのアクセス許可に基づいて表示できるドキュメントのセットを表示します。

• インデックス内のすべてのドキュメントを表示して、一部がエンド ユーザーに表示されない理由を調査します。

これらのタスクを実行するには、カスタム ヘッダー ( x-ms-enable-elevated-read: true) をクエリに追加します。

管理者特権での読み取り要求のアクセス許可

検索インデックスデータ寄稿者アクセス許可、または昇格読み取りアクセス許可を含むカスタムロールが必要です。

クエリはデータ プレーン操作であるため、カスタム ロールはアトミック データ プレーンのアクセス許可のみで構成できます。 カスタム ロールの場合は、Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read アクセス許可を追加します。

「エレベーテッドリード」ヘッダーをクエリに追加する

アクセス許可を設定したら、クエリを実行できます。 次の例は、検索インデックスに対するクエリ要求です。

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

特定のプレビュー API バージョンでの ACL 機能の重要な動作の変更

REST API バージョン 2025-11-01-previewより前のプレビュー バージョンでは、ユーザー トークンが指定されていない場合でも、サービス API キーまたは承認された Entra ロールを使用しているときに、以前のプレビュー バージョン 2025-05-01-preview および 2025-08-01-preview はすべてのドキュメントを返していました。 ユーザー トークンの存在を検証しなかったアプリケーションは、正しく実装されていないか、ベスト プラクティスに従っていない場合に、エンド ユーザーに誤って結果を公開する可能性があります。

2025 年 11 月以降、この動作は変更されました。

• ACL アクセス許可フィルターは、ACL をサポートするすべてのバージョンでサービス API キーまたは Entra 認証のみを使用している場合でも適用されるようになりました。
• ユーザー トークンを省略した場合、ACL で保護されたコンテンツは返されません。
• トラブルシューティングのためにすべてのドキュメントを表示するには、REST API バージョン 2026-05-01-preview 以降を使用するときに、管理者特権で読み取られたヘッダーを明示的に含める必要があります。

この更新プログラムは、アプリケーションがトークン検証のベスト プラクティスを適用しない場合に、コンテンツを保護するのに役立ちます。

関連するコンテンツ

• チュートリアル: ADLS Gen2 からのインデックスアクセス許可メタデータと、アクセス許可でフィルター処理された結果を使用したクエリ (プレビュー)
• プッシュ REST API を使用したドキュメント アクセス制御リスト (ACL) のインデックス作成 (プレビュー)
• ADLS Gen2 インデクサーを使用してアクセス許可メタデータを取り込み、ユーザー アクセス権に基づいて検索結果をフィルター処理する (プレビュー)
• BLOB インデクサーまたはナレッジ ソースを使用して RBAC スコープのメタデータを取り込む
• SharePoint インデクサーを使用してアクセス許可メタデータを取り込み、ユーザー アクセス権に基づいて検索結果をフィルター処理する (プレビュー)