Python のチャットドキュメントセキュリティの概要

[アーティクル]
06/15/2024

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

承認されたユーザーは、チャットアプリのドキュメントに含まれる回答にアクセスできる必要があります。

認証アクセスが必要な応答を含むチャットアプリのスクリーンショット。

承認されていないユーザーは、閲覧権限のないセキュリティで保護されたドキュメントからの回答にアクセスできないようにする必要があります。

ユーザーがデータにアクセスできないことを示す回答を含むチャットアプリのスクリーンショット。

Note

この記事では、記事内の例とガイダンスの土台として、1 つ以上の AI アプリテンプレートを使用しています。 AI アプリテンプレートは、適切にメンテナンスされ、デプロイが容易なリファレンス実装を提供します。これは、高品質な AI アプリの作成を開始するために役立ちます。

アーキテクチャの概要

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

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

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

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

Microsoft Entra ID による認証を使用し、その認証を Azure AI 検索に渡すことを示すアーキテクチャ図。

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

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

ドキュメントアクセス権を持つユーザーまたはグループの詳細を格納する専用のドキュメントアクセス制御フィールドをインデックスに作成します。
ドキュメントのアクセス制御フィールドに、関連するユーザーまたはグループの詳細を設定します。
ユーザーまたはグループのアクセス許可に変更がある場合は常に、このアクセス制御フィールドを更新します。
インデックスの更新がインデクサーでスケジュールされている場合は、次のインデクサーの実行時に変更が反映されます。インデクサーを使用しない場合は、手動で再インデックスする必要があります。

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

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

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

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

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

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

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

環境変数:

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 のサブスクリプション。無料で作成できます
Azure アカウントのアクセス許可 - Azure アカウントに必要なアクセス許可
- Microsoft Entra ID でアプリケーションを管理するためのアクセス許可。
- ユーザーアクセス管理者や所有者などの、Microsoft.Authorization/roleAssignments/write のアクセス許可。
目的の Azure サブスクリプション内の Azure OpenAI に付与されたアクセス権。現時点では、このサービスへのアクセスは申請によってのみ許可されます。 Azure OpenAI へのアクセスを申請するには、 https://aka.ms/oai/accessのフォームに入力してください。

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

Codespaces (推奨)
Visual Studio Code

GitHub アカウント

開発環境を開く

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

GitHub Codespaces (推奨)
Visual Studio Code

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

重要

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

main GitHub リポジトリの Azure-Samples/azure-search-openai-demo ブランチに新しい GitHub Codespace を作成するプロセスを開始します。
次のボタンを右クリックし、[新しいウィンドウでリンクを開く] を選択して、開発環境とドキュメントの両方を同時に使用できるようにします。
[codespace の作成] ページで、codespace の構成設定を確認した後に、[新しい codespace の作成] を選択します
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] (Dev Containers: コンテナーでフォルダーを開く) を検索して選択して、開発コンテナーでプロジェクトを開きます。開発コンテナーが開くまで待ってから続行します。
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 番目のテナントは、AZURE_AUTH_TENANT_ID 環境変数が Microsoft Graph にアクセスするために使用されます。条件付きアクセスポリシーを持つテナントの場合は、条件付きアクセスポリシーのない 2 番目のテナントの ID を見つけるか、新しいテナントを作成します。

環境変数を設定する

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

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

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

Note

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

チャットアプリを 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 セキュリティフィルターを使用する
- グループセキュリティフィルターを使用する
What does a product manager do? でカードを選択します。
The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics. のような回答が得られます。

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

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

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

この情報を取得したら、role_library.pdf ドキュメントの Azure AI 検索インデックス oids フィールドを更新します。

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

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

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

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

パラメーター	目的
--account-name	Azure ストレージアカウント名
--container-name	この例では、コンテナーの名前は `content` です。
--name	この手順の BLOB 名は `role_library.pdf` です。

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

ユーザー ID を取得する

チャットアプリで、[開発者設定] を選択します。
[ID トークン要求] セクションで、objectidentifier をコピーします。これは次のセクションで USER_OBJECT_ID として説明されています。

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

次のスクリプトを使用して、role_library.pdf に対して Azure AI 検索にある 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	グループまたはユーザーオブジェクト ID (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 検索のファイルに対するアクセス許可が一覧表示されていることを確認します。

./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): `oids`
--acl-action	検索インデックスフィールド`oids`を一覧表示します。その他のオプションには、`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 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 検索に USER_OBJECT_ID が含まれていることを確認する

Azure Portal を開き、AI Search を検索します。
一覧から検索リソースを選択します。
[検索管理 ] - >[インデックス] を選択します。
gptkbindex を選択します。
[表示] - >[JSON ビュー] を選択します。
JSON を次の JSON に置き換えます。
```
{
  "search": "*",
  "select": "sourcefile, oids",
  "filter": "oids/any()"
}
```
これにより、oids フィールドに任意の値があるすべてのドキュメントが検索され、sourcefile および oids フィールドが返されます。
role_library.pdf に OID がない場合、[Azure Search のドキュメントにユーザーアクセス許可を付与] セクションに記載されている手順を実行します。

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

手順を完了しても正しい回答が表示されない場合は、Azure AI Search 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 環境を削除すると、アカウントに対して取得するコアごとの無料時間エンタイトルメントの量を最大化できることが保証されます。

重要

GitHub アカウントのエンタイトルメントの詳細については、「 GitHub Codespaces に月単位で含まれるストレージとコア時間」を参照してください。

GitHub Codespaces ダッシュボード (https://github.com/codespaces) にサインインします。
Azure-Samples/azure-search-openai-demo GitHub リポジトリをソースとして現在実行中の Codespaces を見つけます。
codespace のコンテキストメニューを開いた後に、 [削除]を選択します。

ヘルプを参照する

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

トラブルシューティング

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

認証テナントを提供する

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

次のコマンドを実行して、認証テナントに 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 検索を使用した生成 AI アプリでのアクセス制御
Azure API Management を使用してエンタープライズ対応の OpenAI ソリューションを構築する
ハイブリッド検索とランク付け機能を使用した優れたベクトル検索

次の方法で共有

Python のチャットドキュメントセキュリティの概要

アーキテクチャの概要

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

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

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

前提条件

開発環境を開く

Azure CLI で必要な情報を取得する

環境変数を設定する

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

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

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

ユーザー ID を取得する

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

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

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

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

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

GitHub Codespaces をクリーンアップする

ヘルプを参照する

トラブルシューティング

認証テナントを提供する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Python のチャット ドキュメント セキュリティの概要

アーキテクチャの概要

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

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

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

前提条件

開発環境を開く

Azure CLI で必要な情報を取得する

環境変数を設定する

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

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

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

ユーザー ID を取得する

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

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

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

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

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

GitHub Codespaces をクリーンアップする

ヘルプを参照する

トラブルシューティング

認証テナントを提供する

次のステップ

フィードバック

その他のリソース

Python のチャットドキュメントセキュリティの概要

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

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

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

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

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