Python のチャットドキュメントセキュリティを始める

[アーティクル]
01/04/2025

独自のデータで取得拡張生成 (RAG) パターンを使用してチャットアプリケーションを構築する場合は、各ユーザーがアクセス許可に基づいて回答を受け取っていることを確認します。この記事のプロセスに従って、チャットアプリにドキュメントアクセス制御を追加します。

承認済みユーザー: このユーザーは、チャットアプリのドキュメントに含まれる回答にアクセスできる必要があります。
未承認のユーザー: このユーザーは、表示する権限を持たないセキュリティで保護されたドキュメントからの回答にアクセスすることはできません。

手記

この記事では、記事の例とガイダンスの基礎として 1 つ以上の AI アプリテンプレートを使用します。 AI アプリテンプレートを使用すると、デプロイが容易な保守性の高い参照実装が提供されます。 AI アプリの高品質な開始点を確保するのに役立ちます。

アーキテクチャの概要

ドキュメントセキュリティ機能がない場合、エンタープライズチャットアプリには、Azure AI Search と Azure OpenAI を使用した単純なアーキテクチャがあります。回答は、Azure OpenAI GPT モデルからの応答と組み合わせて、ドキュメントが格納されている Azure AI Search へのクエリから決定されます。この単純なフローでは、ユーザー認証は使用されません。

ドキュメントが格納されている Azure AI Search へのクエリから決定された回答と、Azure OpenAI からのプロンプト応答を組み合わせて示すアーキテクチャ図。

ドキュメントのセキュリティを追加するには、エンタープライズチャットアプリを更新する必要があります。

Microsoft Entra を使用してチャットアプリにクライアント認証を追加します。
ユーザーとグループのアクセス権を検索インデックスに設定するサーバー側ロジックを追加します。

Microsoft Entra ID で認証し、その認証を Azure AI Search に渡す使用を示すアーキテクチャ図。

Azure AI Search では、ネイティブドキュメントレベルのアクセス許可提供されておらず、ユーザーのアクセス許可によってインデックス内から検索結果を変更することはできません。代わりに、アプリケーションで検索フィルターを使用して、特定のユーザーまたは特定のグループからドキュメントにアクセスできるようにします。検索インデックス内には、各ドキュメントに、ユーザーまたはグループの ID 情報を格納するフィルター可能なフィールドが必要です。

承認は Azure AI 検索にネイティブに含まれていないため、ユーザーまたはグループ情報を保持するフィールドを追加してから、一致しないドキュメントをフィルタリングする必要があります。この手法を実装するには、次の操作を行う必要があります。

ドキュメントアクセス権を持つユーザーまたはグループの詳細を格納する専用のドキュメントアクセス制御フィールドをインデックスに作成します。
ドキュメントのアクセス制御フィールドに、関連するユーザーまたはグループの詳細を設定します。
ユーザーまたはグループのアクセス許可に変更がある場合は常に、このアクセス制御フィールドを更新します。

インデックスの更新がインデクサーでスケジュールされている場合は、次のインデクサーの実行時に変更が反映されます。インデクサーを使用しない場合は、手動でインデックスを再作成する必要があります。

この記事では、Azure AI Search でドキュメントをセキュリティで保護するプロセス、スクリプトの例を使用して行うことができます。これは、検索管理者が実行するスクリプトの例です。スクリプトは、1 つのドキュメントを 1 つのユーザー ID に関連付けます。これらのスクリプトをし、独自のセキュリティと運用の要件を適用してニーズに合わせてスケーリングできます。

セキュリティ構成を決定する

このソリューションには、このサンプルのドキュメントセキュリティに必要な機能を有効にするブール環境変数が用意されています。

パラメーター	目的
`AZURE_USE_AUTHENTICATION`	`true`に設定すると、チャットアプリへのユーザーサインインと Azure App Service 認証が有効になります。開発者向け設定チャットアプリでを有効にします。
`AZURE_ENFORCE_ACCESS_CONTROL`	`true`に設定すると、ドキュメントアクセスに対する認証が必要になります。オブジェクト ID (OID) とグループセキュリティの開発者向け設定は、UI から無効にできないように有効および無効になっています。
`AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS`	`true`に設定すると、認証されたユーザーは、アクセス制御が必要な場合でも、アクセス制御が割り当てられていないドキュメントを検索できます。このパラメーターは、`AZURE_ENFORCE_ACCESS_CONTROL` が有効になっている場合にのみ使用してください。
`AZURE_ENABLE_UNAUTHENTICATED_ACCESS`	`true`に設定すると、アクセス制御が適用されている場合でも、認証されていないユーザーがアプリを使用できるようになります。このパラメーターは、`AZURE_ENFORCE_ACCESS_CONTROL` が有効になっている場合にのみ使用してください。

このサンプルでサポートされているセキュリティプロファイルを理解するには、次のセクションを使用します。この記事では、Enterprise プロファイルを構成します。

エンタープライズ: 必須アカウント + ドキュメントフィルター

サイトの各ユーザーがサインインする必要があります。サイトには、すべてのユーザーに公開されているコンテンツが含まれています。ドキュメントレベルのセキュリティフィルターは、すべての要求に適用されます。

環境変数:

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true

混在使用: 省略可能なアカウント + ドキュメントフィルター

サイトの各ユーザーがサインインできます。サイトには、すべてのユーザーに公開されているコンテンツが含まれています。ドキュメントレベルのセキュリティフィルターは、すべての要求に適用されます。

環境変数:

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true
AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

前提条件

開発コンテナー環境は、この記事を完了するために必要なすべての依存関係で使用できます。開発コンテナーは、GitHub Codespaces (ブラウザー) で実行することも、Visual Studio Code を使用してローカルで実行することもできます。

この記事を使用するには、次の前提条件が必要です。

Azure サブスクリプション。無料で1つ作成してください。
Azure アカウントのアクセス許可: Azure アカウントには次の権限が必要です。
- Microsoft Entra ID でアプリケーションを管理するためのアクセス許可。
- Microsoft.Authorization/roleAssignments/write アクセス許可 (ユーザーアクセス管理者や所有者など)。

お好みの開発環境に応じて、より多くの前提条件が必要です。

GitHub Codespaces (推奨)
Visual Studio Code

GitHub アカウント

開発環境を開く

この記事を完了するためにすべての依存関係がインストールされている開発環境から始めます。

GitHub Codespaces (推奨)
Visual Studio Code

GitHub Codespaces は、Web 用の Visual Studio Code ユーザーインターフェイスとして GitHub によって管理される開発コンテナーを実行します。最も簡単な開発環境では、GitHub Codespaces を使用して、この記事を完了するために正しい開発者ツールと依存関係がプレインストールされるようにします。

重要

すべての GitHub アカウントでは、2 つのコアインスタンスで毎月最大 60 時間無料で GitHub Codespaces を使用できます。詳細については、GitHub Codespaces の毎月含まれるストレージとコア時間に関する情報については、およびを参照してください。

Azure-Samples/azure-search-openai-demo GitHub リポジトリの main ブランチに新しい GitHub コードスペースを作成するプロセスを開始します。
以下のボタンを右クリックして、新しいウィンドウでリンクを開く を選択すると、開発環境とドキュメントを同時に利用できます。
[codespace の作成] ページで、コードスペースの構成設定を確認し、[新しいコードスペースの作成] を選択します。
コードスペースが起動するまで待ちます。このスタートアッププロセスには数分かかる場合があります。
画面の下部にあるターミナルで、Azure Developer CLI を使用して Azure にサインインします。
```
azd auth login
```
認証プロセスを完了します。
この記事の残りのタスクは、この開発コンテナーのコンテキストで行われます。

Visual Studio Code 用の Dev Containers 拡張機能では、ローカルコンピューター Docker をインストールする必要があります。拡張機能は、Docker ホストを使用して開発コンテナーをローカルでホストし、この記事を完了するために正しい開発者ツールと依存関係がプレインストールされています。

プロジェクトのコンピューターに新しいローカルディレクトリを作成します。
```
mkdir my-intelligent-app && cd my-intelligent-app
```
そのディレクトリで Visual Studio Code を開きます。
```
code .
```
Visual Studio Code で新しいターミナルを開きます。
次の AZD コマンドを実行して、GitHub リポジトリをローカルコンピューターに移動します。
```
azd init -t azure-search-openai-demo
```
コマンド パレットを開き、Dev Containers: Open Folder in Container を検索して選択し、開発コンテナーでプロジェクトを開きます。続行する前に、開発コンテナーが開くまで待ちます。
Azure Developer CLI を使用して Azure にサインインします。
```
azd auth login
```
ターミナルからコードをコピーし、ブラウザーに貼り付けます。手順に従って、Azure アカウントで認証します。
このプロジェクトの残りの演習は、この開発コンテナーのコンテキストで行われます。

Azure CLI を使用して必要な情報を取得する

次の Azure CLI コマンドを使用して、サブスクリプション ID とテナント ID を取得します。 AZURE_TENANT_ID 値として使用する値をコピーします。

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

テナントの条件付きアクセスポリシーに関するエラーが発生した場合は、条件付きアクセスポリシーのない 2 つ目のテナントが必要です。

ユーザーアカウントに関連付けられている最初のテナントは、AZURE_TENANT_ID 環境変数に使用されます。
条件付きアクセスのない 2 番目のテナントは、microsoft Graph にアクセスするために AZURE_AUTH_TENANT_ID 環境変数に使用されます。条件付きアクセスポリシーを持つテナントの場合は、条件付きアクセスポリシーのない 2 番目のテナントの ID を見つけるか、新しいテナントを作成。

環境変数を設定する

次のコマンドを実行して、Enterprise プロファイルのアプリケーションを構成します。

azd env set AZURE_USE_AUTHENTICATION true
azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
azd env set AZURE_ENFORCE_ACCESS_CONTROL true

次のコマンドを実行してテナントを設定します。テナントは、ユーザーがホストされているアプリケーション環境にサインインすることを承認します。 <YOUR_TENANT_ID> をテナント ID に置き換えます。
```
azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
```

手記

ユーザーテナントに条件付きアクセスポリシーがある場合は、認証テナントを指定必要があります。

チャットアプリを Azure にデプロイする

デプロイは、次の手順で構成されます。

Azure リソースを作成します。
ドキュメントをアップロードします。
Microsoft Entra ID アプリ (クライアントとサーバー) を作成します。
ホスティングリソースの ID を有効にします。

次の Azure Developer CLI コマンドを実行して、Azure リソースをプロビジョニングし、ソースコードをデプロイします。
```
azd up
```

次の表を使用して、AZD 展開プロンプトに回答します。

Prompt	答え
環境名	エイリアスやアプリなどの識別情報を含む短い名前を使用します。そして、例は `tjones-secure-chat`です.
予約	リソースを作成するサブスクリプションを選択します。
Azure リソースの場所	近くの場所を選択します。
`documentIntelligentResourceGroupLocation` の場所	近くの場所を選択します。
`openAIResourceGroupLocation` の場所	近くの場所を選択します。

アプリがデプロイされてから 5 分または 10 分待って、アプリの起動を許可します。

アプリケーションが正常にデプロイされると、ターミナルに URL が表示されます。
(✓) Done: Deploying service webapp というラベルの付いた URL を選択して、ブラウザーでチャットアプリケーションを開きます。
アプリ認証のポップアップに同意します。
チャットアプリが表示されたら、右上隅にユーザーがサインインしていることに注意してください。
開発者設定開き、次のオプションの両方が選択され、変更が無効になっていることがわかります。
- oid セキュリティフィルター を使用する
- グループのセキュリティフィルター を使用する
プロダクトマネージャーは何をするのかが書かれているカードを選択します。
次のような回答が得られます。提供されるソースには、Contoso Electronics のプロダクトマネージャーの役割に関する特定の情報が含まれていません。

ユーザーのドキュメントへのアクセスを開く

回答を得ることができるように、正確なドキュメントのアクセス許可を有効にします。いくつかの情報が必要です。

Azure Storage
- アカウント名
- コンテナー名
- role_library.pdf の BLOB/ドキュメント URL
Microsoft Entra ID のユーザー ID

この情報がわかったら、role_library.pdf ドキュメントの Azure AI Search インデックス oids フィールドを更新します。

ストレージ内のドキュメントの URL を取得する

プロジェクトのルートにある .azure フォルダーで、環境ディレクトリを見つけて、そのディレクトリを含む .env ファイルを開きます。
AZURE_STORAGE_ACCOUNT エントリを検索し、その値をコピーします。

次の Azure CLI コマンドを使用して、content コンテナー内の role_library.pdf BLOB の URL を取得します。

az storage blob url \
    --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
    --container-name 'content' \
    --name 'role_library.pdf'

パラメーター	目的
--account-name	Azure Storage アカウント名。
--コンテナネーム	このサンプルのコンテナー名は `content`です。
--名前	この手順の BLOB 名は `role_library.pdf`です。

後で使用する BLOB URL をコピーします。

ユーザー ID を取得する

チャットアプリで、[開発者向け設定]選択します。
[ID トークン要求] セクションで、objectidentifier パラメーターをコピーします。このパラメーターは、次のセクションで USER_OBJECT_IDと呼ばれます。

Azure Search でドキュメントへのユーザーアクセスを提供する

次のスクリプトを使用して、Azure AI Search for role_library.pdf の oids フィールドにアクセスできるように変更します。

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action add \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

パラメーター	目的
-v	詳細出力。
--acl-type	グループ OID またはユーザー OID: `oids`。
--acl-action	検索インデックスフィールドにを追加します。その他のオプションには、`remove`、`remove_all`、および `list`があります。
--acl	グループまたはユーザー `USER_OBJECT_ID`。
--url	`https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`など、Azure Storage 内のファイルの場所。 CLI コマンドで URL を引用符で囲まないでください。

このコマンドのコンソール出力は次のようになります。

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents

必要に応じて、次のコマンドを使用して、Azure AI Search のファイルに対するアクセス許可が一覧表示されていることを確認します。

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action list \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

パラメーター	目的
-v	詳細出力。
--acl-type	グループ OID またはユーザー OID: `oids`。
--acl-action	検索インデックスのフィールド `oids`を一覧に追加します。その他のオプションには、`remove`、`remove_all`、および `list`があります。
--acl	グループまたはユーザーの `USER_OBJECT_ID` パラメーター。
--url	表示されているファイルの場所 (`https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf` など)。 CLI コマンドで URL を引用符で囲まないでください。

このコマンドのコンソール出力は次のようになります。

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
[00000000-0000-0000-0000-000000000000]

出力の最後にある配列には、USER_OBJECT_ID パラメーターが含まれており、ドキュメントが Azure OpenAI の回答で使用されているかどうかを判断するために使用されます。

Azure AI Search にUSER_OBJECT_IDが含まれていることを確認する

Azure portal を開き、AI Searchを検索します。
一覧から検索リソースを選択します。
検索管理>インデックスを選択します。
gptkbindexを選択する。
[表示]>[JSON ビュー] を選択します。
JSON を次の JSON に置き換えます。
```
{
  "search": "*",
  "select": "sourcefile, oids",
  "filter": "oids/any()"
}
```
この JSON は、oids フィールドに値があるすべてのドキュメントを検索し、sourcefile フィールドと oids フィールドを返します。
role_library.pdf に OID がない場合は、Azure Search でドキュメントへのアクセス権をユーザーに提供するセクションに戻り、手順を完了します。

ドキュメントへのユーザーアクセスを確認する

手順を完了しても正しい回答が表示されない場合は、azure AI Search for role_library.pdfで USER_OBJECT_ID パラメーターが正しく設定されていることを確認します。

チャットアプリに戻ります。もう一度サインインすることが必要な場合があります。
同じクエリを入力して、role_library コンテンツが Azure OpenAI の回答で使用されるようにします:What does a product manager do?。
結果を表示します。この結果には、ロールライブラリドキュメントからの適切な回答が含まれます。

リソースのクリーンアップ

次の手順では、使用したリソースをクリーンアップするプロセスについて説明します。

Azure リソースをクリーンアップする

この記事で作成した Azure リソースは、Azure サブスクリプションに課金されます。今後これらのリソースが必要になるとは思わない場合は、削除して、より多くの料金が発生しないようにします。

次の Azure Developer CLI コマンドを実行して、Azure リソースを削除し、ソースコードを削除します。

azd down --purge

GitHub Codespaces と Visual Studio Code をクリーンアップする

次の手順では、使用したリソースをクリーンアップするプロセスについて説明します。

GitHub Codespaces
Visual Studio Code

GitHub Codespaces 環境を削除すると、アカウントに対して取得するコア時間単位の無料エンタイトルメントの量を最大化できます。

重要

GitHub アカウントの権限について詳しく知りたい場合は、「GitHub Codespaces の月次ストレージとコア時間の含有量」をご覧ください。

GitHub Codespaces ダッシュボードにサインインします。
現在実行中のコードスペースを、Azure-Samples/azure-search-openai-demo GitHub リポジトリから取得したものとして特定します。
コードスペースのコンテキストメニューを開き、[の削除] 選択します。

助けを求める

このサンプルリポジトリでは、トラブルシューティング情報を提供します。

トラブルシューティング

このセクションでは、この記事に固有の問題のトラブルシューティングについて説明します。

認証テナントを提供する

認証がホスティングアプリケーションとは別のテナントにある場合は、次のプロセスでその認証テナントを設定する必要があります。

次のコマンドを実行して、認証テナントに 2 番目のテナントを使用するようにサンプルを構成します。
```
azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
```
パラメーター目的

AZURE_AUTH_TENANT_ID AZURE_AUTH_TENANT_ID が設定されている場合は、アプリをホストするテナントです。
次のコマンドを使用してソリューションを再デプロイします。
```
azd up
```

パラメーター	目的
`AZURE_AUTH_TENANT_ID`	`AZURE_AUTH_TENANT_ID` が設定されている場合は、アプリをホストするテナントです。

Azure OpenAI ベストプラクティスソリューションアーキテクチャを使用してチャットアプリを構築します。
Azure AI Searchを使用した生成 AI アプリでのアクセス制御について説明します。
Azure API Managementを使用して、エンタープライズ対応の Azure OpenAI ソリューションを構築します。
Azure AI Search: ハイブリッド取得とランキング機能によってベクター検索を上回る性能を示すを参照してください。

次の方法で共有

Python のチャットドキュメントセキュリティを始める

アーキテクチャの概要

セキュリティ構成を決定する

エンタープライズ: 必須アカウント + ドキュメントフィルター

混在使用: 省略可能なアカウント + ドキュメントフィルター

前提条件

開発環境を開く

Azure CLI を使用して必要な情報を取得する

環境変数を設定する

チャットアプリを Azure にデプロイする

ユーザーのドキュメントへのアクセスを開く

ストレージ内のドキュメントの URL を取得する

ユーザー ID を取得する

Azure Search でドキュメントへのユーザーアクセスを提供する

Azure AI Search にUSER_OBJECT_IDが含まれていることを確認する

ドキュメントへのユーザーアクセスを確認する

リソースのクリーンアップ

Azure リソースをクリーンアップする

GitHub Codespaces と Visual Studio Code をクリーンアップする

助けを求める

トラブルシューティング

認証テナントを提供する

フィードバック

その他のリソース

次の方法で共有

Python のチャットドキュメントセキュリティを始める

アーキテクチャの概要

セキュリティ構成を決定する

エンタープライズ: 必須アカウント + ドキュメント フィルター

混在使用: 省略可能なアカウント + ドキュメント フィルター

前提 条件

開発環境を開く

Azure CLI を使用して必要な情報を取得する

環境変数を設定する

チャット アプリを Azure にデプロイする

ユーザーのドキュメントへのアクセスを開く

ストレージ内のドキュメントの URL を取得する

ユーザー ID を取得する

Azure Search でドキュメントへのユーザー アクセスを提供する

Azure AI Search にUSER_OBJECT_IDが含まれていることを確認する

ドキュメントへのユーザー アクセスを確認する

リソースのクリーンアップ

Azure リソースをクリーンアップする

GitHub Codespaces と Visual Studio Code をクリーンアップする

助けを求める

トラブルシューティング

認証テナントを提供する

関連コンテンツ

フィードバック

その他のリソース

エンタープライズ: 必須アカウント + ドキュメントフィルター

混在使用: 省略可能なアカウント + ドキュメントフィルター

前提条件

チャットアプリを Azure にデプロイする

Azure Search でドキュメントへのユーザーアクセスを提供する

ドキュメントへのユーザーアクセスを確認する