Deep Data Security

Oracle Agent Memoryは、Oracle Deep Data Security (Deep Sec)と統合され、Oracle AI Database内でエンド・ユーザー認可を適用します。Deep Secはセキュリティ機能です。データ・ロール、データ権限、エンドユーザー・セキュリティ・コンテキストによって、リクエストが読み取ったり変更したりできる管理対象メモリー行が決まります。

重要:このページのAPIは、セキュリティ管理およびリクエスト・セキュリティ・インタフェースとして扱います。ポリシー管理、管理対象スキーマの所有権およびランタイム接続プーリングには、個別のデータベース・アイデンティティを使用します。ランタイム・プール・アカウントには、保護されたエージェント・メモリー表へのフォールバック・アクセスを提供する直接権限を指定しないでください。

Oracleのディープ・データ・セキュリティの概要では、データベース認可モデルについて説明します。完全なOCI IAMデプロイメントについては、Deep Data Securityによるエンド・ユーザー・メモリー分離の強制を参照してください。

セキュリティ・モデル

エージェント・メモリー統合では、次の2つのポリシーがサポートされています。

ポリシー 効果的なアクセス
UserOwnRowsDeepDataSecurityPolicy 所有者がORA_END_USER_CONTEXT.usernameと一致する場合のみ、ユーザー・スコープのエージェント・メモリー行の読取りおよび書込みを行います。メモリー・リンク読取りでは、割り当てられたポリシーで両方のエンドポイント・メモリーが読取り可能である必要があります。リンク書込みでは、両方のエンドポイント・メモリーがそのユーザーに属している必要があります。
GlobalMemoriesDeepDataSecurityPolicy user_idがNULLのスコープなしメモリー行を読み取ります。このポリシーは、書込みまたはアクセス権を別のユーザーのスコープ付きメモリーに付与しません。両方のエンドポイント・メモリーがアクティブ・ポリシーで読取り可能な場合に、メモリー・リンクを公開します。このポリシーのみでは、両方のエンドポイントがグローバル・メモリーである必要があります。独自の行ポリシーと組み合せると、所有メモリーとグローバル・メモリー間のリンクも表示されます。

ポリシー・オブジェクトは、管理APIでは不透明な選択です。管理対象表、データ・ロール、データ・グラントおよびSQL実装はプライベートのままであるため、Oracle Agent Memoryはデータベース・スキーマを安全に進化させることができます。カスタム・ポリシー・サブクラスはサポートされていません。前述の2つのポリシー・クラスのいずれかを使用してください。

ポリシーの範囲は、owner_schemaとmemory_store_idの組合せです。あるストアに対してポリシーを作成または割り当てても、別の所有者スキーマに同じIDのストアを含め、別のストアにはポリシーが割り当てられません。

UserOwnRowsDeepDataSecurityPolicyポリシーでは、列ごとの書込みも制限されます。エンド・ユーザーは、所有行を挿入するときにID列と所有権列を設定できますが、後でこれらの列を変更することはできません。ポリシーは、次の書込みサーフェスを付与します。

UserOwnRowsDeepDataSecurityPolicyの列レベルの書込み権限

管理対象表 挿入可能な列 更新可能なカラム
スレッド record_id, user_id, agent_id, metadata, runtime_config, runtime_state metadata, runtime_config, runtime_state
スレッド要約 record_id, thread_id, user_id, agent_id, space_id, content, metadata, status content, metadata, status
メッセージ record_id, thread_id, user_id, agent_id, message_role, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at
ドキュメント record_id, message_id, thread_id, user_id, agent_id, space_id, document_type, description, blob, timestamp, metadata, document_metadata, expires_at, status description, blob, timestamp, metadata, document_metadata, expires_at
メモリー record_id, thread_id, user_id, agent_id, memory_type, content, timestamp, metadata, expires_at, status content, timestamp, metadata, expires_at, status
メモリー・リンク relation_id, source_memory_id, source_memory_user_id, target_memory_id, target_memory_user_id, relation_type, opposite_relation_type, timestamp, metadata relation_type, opposite_relation_type, timestamp, metadata
ユーザーアクタープロファイル actor_id, actor_type, information, metadata, status information, metadata
チャンクの記録 ストアがベクトルを保持する場合、source_id、source_record_type、source_emb_column、chunk_seq、chunk_text、thread_id、user_id、agent_id、statusおよびembedding status

SELECTおよびDELETEは、行スコープのままです。chunk_id、created_at、order_seqなどの生成列、作成時列および予約列は、前述の明示的なリストがないかぎり、エンド・ユーザーによって挿入または更新できません。データベースでは挿入の行述語もチェックされるため、user_idを挿入可能としてリストしても、エンド・ユーザーは別のアイデンティティが所有する行を作成できません。UPDATEが、他の列にUPDATEを付与する表の更新不可能な列をターゲットとする場合、Deep Secはエラーを発生させるのではなく、行を変更せずに静かに残すことができます。レコード・チャンクでは、statusの更新のみが許可されます。SDKは、チャンク・アイデンティティ、テキストおよび埋込み値の変更を、削除および挿入操作に置き換えます。アプリケーションは、SDKでサポートされている突然変異メソッドを使用し、保護された値が変更されたことを証明するために、直接SQL実行のみを処理しないでください。

次の順序で管理APIを使用します。

  1. 管理対象エージェント・メモリー・ストアをスキーマ所有者として作成します。
  2. セキュリティ管理者としてadd_deep_data_security_policies()をコールします。
  3. 認可されたOCI IAMグループまたはローカルのDeep Secエンド・ユーザーごとに、grant_agent_memory_policies()をコールします。
  4. 実行時に、OracleMemoryEndUserSecurityContextのすべてのエージェント・メモリー操作をラップします。
  5. 不要になったポリシーを削除する前に、割当てを取り消します。

ランタイム操作でOracleDBEmbedderをデフォルトのprovider="database"とともに使用し、Oracle AI Databaseに格納されたモデル(通常はONNXモデル)を使用する場合、ポリシーは前述のエージェント・メモリー認可表のみを付与します。IAMグループのマップされたデータ・ロールも、データベース常駐モデルにアクセスできる必要があります。リクエストを処理する前に、「Deep Secでのデータベース内埋込みモデルの使用」の説明に従って、そのアクセスを構成します。

OracleDBEmbedderでは、DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDINGを介してリモート・プロバイダを使用することもできます。この構成では、データベース常駐モデルは使用されず、SELECT ON MINING MODELは必要ありません。リモート・プロバイダのOracle資格証明とネットワーク・アクセスを個別に構成します。エージェント・メモリー操作は、引き続きOracleMemoryEndUserSecurityContext内で実行する必要があります。

管理コールは、データベースの変更をコミットしてから戻ります。基礎となるロールおよび権限付与の概念については、Oracleのデータ・アクセス制御構成を参照してください。

コンテキスト使用チェック

保護されたアプリケーションの作業が実行される前に、SDKは安全でない組合せを拒否します。

これらのチェックにより、不正なSDK実行パスが診断されます。Oracle AI Databaseのデータ権限は認可境界のままで、認証されたエンド・ユーザーがアクセスできる行および列の決定を続行します。

ポリシー

クラス oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

ベース: object

サポートされているOracle Agent Memory Deep Data Securityポリシーを識別します。

ポリシー・オブジェクトは、ディープ・データ・セキュリティ管理機能に渡される不透明な選択です。UserOwnRowsDeepDataSecurityPolicyまたはGlobalMemoriesDeepDataSecurityPolicyをインスタンス化します。管理対象表、データ・ロール、データ権限およびSQLを含むポリシー実装の詳細は、Oracle Agent Memoryに対してプライベートなままであり、リリース間で変更される可能性があります。

このクラスはカスタム・ポリシー拡張ポイントではありません。Oracle Agent Memoryによって提供される2つのポリシー・クラス以外のサブクラスは、管理関数によって拒否されます。

例

エンド・ユーザー行およびスコープ指定されていないグローバル・メモリーのポリシー・セットを作成します。

policies = [
    UserOwnRowsDeepDataSecurityPolicy(),
    GlobalMemoriesDeepDataSecurityPolicy(),
]

クラス oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

ベース: DeepDataSecurityPolicy

認証されたエンド・ユーザーが所有する行へのアクセス権を付与します。

このポリシーは、行スコープのSELECT、列スコープのINSERTおよびUPDATE、およびユーザー所有データに対する行スコープのDELETEを付与します。所有権、レコード・タイプ、生成済、作成時および予約済の列は、挿入後に変更できません。レコード・チャンクは挿入および削除できますが、SDKによって完全な行として置換されるため、更新できません。このポリシーにより、ランタイム・ストアの初期化に必要なレジストリ読取りも付与されます。メモリー・リンクSELECTは共有エンドポイント可視性ルールに従いますが、リンクINSERT、UPDATEおよびDELETEでは、両方のエンドポイント・メモリーがエンド・ユーザーに属している必要があります。

例

policy = UserOwnRowsDeepDataSecurityPolicy()

クラス oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

ベース: DeepDataSecurityPolicy

グローバル・メモリーおよび可視メモリー間のリンクへの読取りアクセス権を付与します。

このポリシーは、user_idがNULLであるメモリー行にSELECTを付与し、ランタイム・ストアの初期化に必要なレジストリ読取りを付与します。そのメモリー・リンク読取り権限は、割り当てられたディープ・データ・セキュリティ・ポリシーの下でエンド・ユーザーが両方のエンドポイント・メモリーを読み取ることができる場合に、リンクを公開します。したがって、このポリシーのみでは、両方のエンドポイントがグローバル・メモリーである必要があります。独自の行ポリシーと組み合せると、所有メモリーとグローバル・メモリーの間のリンクも表示されます。別のユーザーのスコープ付きメモリーへの書込みまたはアクセスは許可されません。

例

policy = GlobalMemoriesDeepDataSecurityPolicy()

プリンシパル

割当は、アクセス・トークンのgroupカスタム・クレームまたはローカルのDeep Secエンド・ユーザーに含まれるOCI IAMグループのいずれかをターゲットとします。OCI IAMグループ情報は、Oracle AI Databaseが外部データ・ロールにマップする前に、カスタム・クレームとして構成する必要があります。OCI IAMでのグループ情報のカスタム・クレームの構成を参照してください。

クラス oracleagentmemory.core.deepsec.Principal

ベース: object

エージェント・メモリー・ポリシーの割当てを受信するユーザーを識別するベース・タイプ。

プリンシパルは、grant_agent_memory_policies()またはrevoke_agent_memory_policies()をターゲットとするセキュリティIDです。プリンシパルは、ディープ・データ・セキュリティのデータ・ロールまたはデータによって特定のエージェント・メモリー・ストアへのアクセスを制御できる権限受領者を識別します。サポートされている現在のプリンシパル・タイプは、OCI IAMグループおよびローカルDBエンド・ユーザーです。

OCI IAMグループにはOciGroupPrincipalを、データベース管理のディープ・データ・セキュリティ・エンド・ユーザーにはLocalEndUserPrincipalを使用します。直接Principalインスタンスを管理関数に渡すことはサポートされていません。

クラス oracleagentmemory.core.deepsec.OciGroupPrincipal

ベース: Principal

エージェント・メモリー・ポリシーを受信するOCI IAMグループを識別します。

クラス oracleagentmemory.core.deepsec.LocalEndUserPrincipal

ベース: Principal

ポリシーを受け取るローカルDeep Data Securityエンド・ユーザーを識別します。

管理

専用のセキュリティ管理接続を介してこれらの機能を実行します。クロススキーマ・エージェント・メモリー表の場合、そのアカウントには、CREATE ANY DATA GRANT、DROP ANY DATA GRANT、ADMINISTER ANY DATA GRANTなどの適用可能なDeep Sec管理権限と、データ・ロールを作成および削除する権限が必要です。これらの権限をランタイム・プール・アカウントに付与しないでください。

oracleagentmemory.core.deepsec.add_deep_data_security_policies

エージェント・メモリー・ポリシーのデータ・ロールおよびデータ権限を作成します。

ポリシーの範囲は、1つのowner_schemaおよびmemory_store_idです。これを追加すると、保護された管理対象表にディープ・データ・セキュリティを強制的に適用できます。ポリシーを再追加すると、エージェント・メモリー管理のデータ・ロールと権限付与が現在の定義に置き換えられます。繰返しコールはべき等です。OracleがポリシーDDLの一部を中断前にコミットした場合、同じコールを再試行すると、管理対象の定義が修復されます。

このファンクションは、戻す前に接続をコミットします。スキーマ所有者またはランタイム・アプリケーション接続ではなく、専用のセキュリティ管理接続を使用します。

例

独自行およびグローバル・メモリー・アクセス・ポリシーを追加します。

add_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[
        UserOwnRowsDeepDataSecurityPolicy(),
        GlobalMemoriesDeepDataSecurityPolicy(),
    ],
)

oracleagentmemory.core.deepsec.remove_deep_data_security_policies

エージェント・メモリー・ディープ・データ・セキュリティ・ポリシーを削除します。

ポリシー・ロールを削除すると、そのロールもデータ権限およびローカル・エンドユーザー割当てから削除されます。外部データ権限として作成されたOCI IAM割当ては、最初にrevoke_agent_memory_policies()を使用して削除する必要があります。管理対象表に対して必須のデータ権限強制が無効になるのは、その表にデータ権限が残っていない場合のみです。

このファンクションは、戻す前に接続をコミットします。

例

独自行ポリシーを削除します。

remove_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_deep_data_security_policies

Oracle AI Databaseで現在作成されているエージェント・メモリー・ポリシーをリストします。

例

構成済ポリシー・タイプの検査:

policies = list_deep_data_security_policies(
    connection,
    owner_schema="MY_OWNER_SCHEMA",
    memory_store_id="MEMORY",
)
[type(policy).__name__ for policy in policies]
['UserOwnRowsDeepDataSecurityPolicy']

oracleagentmemory.core.deepsec.grant_agent_memory_policies

エージェント・メモリー・ポリシーをOCI IAMグループまたはローカル・エンド・ユーザーに付与します。

OCI IAMグループは、外部にマップされたデータ・ロールで表されます。Oracle AI Databaseでは、外部マップされたデータ・ロールがローカル管理データ・ロールを受け取ることが許可されていないため、各ポリシーのデータ権限はそのマップされたロールに直接アタッチされます。

割り当てる前に、add_deep_data_security_policies()を使用してターゲット・ストアの各ポリシーを作成します。このファンクションは、戻す前に接続をコミットします。繰返しコールはべき等です。OracleがOCI IAM割当ての一部を中断前にコミットした場合、同じコールを再試行すると、欠落している管理対象データ権限が再作成されます。

例

OCI IAMグループへの独自行アクセス権の付与:

grant_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.revoke_agent_memory_policies

OCI IAMグループまたはローカル・エンド・ユーザーからエージェント・メモリー・ポリシーを取り消します。

主体そのものが保存されます。特に、OCI IAMグループの外部にマップされたデータ・ロールは、このまたは別のエージェント・メモリー・ストアからの割当てに使用できるままです。

失効により、データベース・ポリシーの状態が変更され、コミットされてから戻ります。そのため、後続の保護されたデータベース文では、取り消されたポリシーが受信されなくなります。これは、OCI IAMグループからのユーザーの削除とは異なります。すでに発行されているアクセス・トークンは、そのトークンが期限切れになるまで、その埋込みグループ・クレームを保持します。

例

OCI IAMグループから独自行アクセスを取り消します。

revoke_agent_memory_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
    principals=[OciGroupPrincipal("ORACLEAGENTMEMORY_USERS")],
    policies=[UserOwnRowsDeepDataSecurityPolicy()],
)

oracleagentmemory.core.deepsec.list_agent_memory_granted_policies

各プリンシパルに割り当てられたプリンシパルおよびエージェント・メモリー・ポリシーをリストします。

例

ポリシー割当てのリスト:

assignments = list_agent_memory_granted_policies(
    connection,
    memory_store_id="MEMORY",
    owner_schema="MY_OWNER_SCHEMA",
)
len(assignments) >= 0
True

ランタイム・セキュリティ・コンテキスト

OracleMemoryEndUserSecurityContextは、python-oracledbセキュリティ・コンテキストをエージェント・メモリー操作にスコープ指定します。コンテキストはエンド・ユーザー・トークンとデータベース・アクセス・トークンを保持し、Oracle AI Databaseはそれらを検証し、要求からアクティブなデータ・ロールを導出します。SDKは、取得した各物理接続にコンテキストをアタッチし、クリアしてからその接続をプールに戻します。

セキュリティ・モデルについては、Oracleのエンドユーザー・セキュリティ・コンテキスト、検証、ロール解決、接続再利用およびコンテキスト・クリーンアップについては、データベース・サーバーがエンドユーザー・セキュリティ・コンテキストを管理する方法を参照してください。

クラス oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

ベース: object

エージェント・メモリー操作にOracleエンドユーザー・セキュリティ・コンテキストを適用します。

このコンテキスト・マネージャを入力すると、現在の実行コンテキストで使用されるOracleバック・エージェント・メモリー・ストアでsecurity_contextが使用可能になります。各データベース操作は、物理接続の取得後にコンテキストを適用し、エンド・ユーザー・アイデンティティがアクティブであることを検証し、接続を解放する前にコンテキストをクリアします。この動作は、直接接続と接続プールの両方で機能します。

スコープは、待機中の非同期エージェント・メモリー・コールに伝播されます。withまたはasync withブロックを超える呼出し側タスクは、期限切れのスコープを使用できません。ブロック内で受け入れられたバックグラウンド・メモリー抽出ジョブは、プライベート・スナップショットを保持するため、ブロックの終了後に完了できます。

エンド・ユーザーまたはデータベース・アクセス・トークンが変更された場合は、新しいoracledb.EndUserSecurityContextを使用します。Oracle AI Databaseは、指定されたトークンの要求から有効なデータ・ロールを導出します。このマネージャは、OAuthトークンをリフレッシュ、取消または検査しません。

ノート

このクラスは、Oracle Agentのメモリー操作をスコープ指定します。SDK外部のアプリケーションSQLによって直接使用される任意の接続は変更されません。ネストはサポートされており、同じマネージャ・インスタンスのネストも含まれます。各イグジットは、一致するエントリからコンテキストを復元します。

例

OAuth派生コンテキストを同期エージェント・メモリー操作に適用します:

import oracledb
from oracleagentmemory.core.deepsec import (
    OracleMemoryEndUserSecurityContext,
)
user_context = oracledb.create_end_user_security_context(
    end_user_identity=end_user_token,
    database_access_token=database_access_token,
)
with OracleMemoryEndUserSecurityContext(user_context):
    memory_store.add(
        ["Remember this preference."],
        record_type="memory",
    )

同じマネージャが非同期コールをサポートします。

async with OracleMemoryEndUserSecurityContext(user_context):
    await memory_store.add_async(
        ["Remember this preference."],
        record_type="memory",
    )

method __aenter__ (非同期)

待機中のエージェント・メモリー操作のスコープを入力します。

method __aexit__ (非同期)

ブロック例外を抑制せずに非同期スコープを終了します。

メソッド __enter__

スコープを入力し、このコンテキスト・マネージャを返します。

現在の実行コンテキストで開始されたエージェント・メモリー操作は、一致する終了までこのマネージャのエンドユーザー・セキュリティ・コンテキストを使用します。

メソッド __exit__

スコープを終了し、継承された呼び出し元タスクがスコープを再利用しないようにします。

管理対象ブロックからの例外は変更なしで伝播されます。

oracleagentmemory.core.deepsec.get_end_user_username

Oracle DB接続にアタッチされたエンド・ユーザー・ユーザー名を返します。

Deep Data Securityは、データベース接続にアタッチされたエンド・ユーザー・セキュリティ・コンテキストを使用してデータ権限を評価します。このヘルパーは、そのコンテキストからusername属性を読み取ります。物理接続の確立に使用されるデータベース・アカウントは返されません。

例

接続にアタッチされたエンドユーザー・アイデンティティがあるかどうかを確認します:

get_end_user_username(conn) is None
True

監査

Deep Secでは、Oracle AI Database Unified Auditingを使用しています。データベース管理者は、Deep Sec構成操作(データ・ロールとデータ権限の作成または削除、データ・ロールの付与または取消し、エンド・ユーザーおよびエンド・ユーザー・コンテキストの作成または削除など)の統合監査ポリシーを作成できます。監査レコードは、UNIFIED_AUDIT_TRAILを介して使用でき、エンド・ユーザー・セキュリティ・コンテキストで実行されるアクティビティのエンド・ユーザーIDおよびセキュリティコンテキスト識別子を含めることができます。

CREATE END USER SECURITY CONTEXTアクションは、セキュリティ・コンテキストの作成を記録します。Oracleでは、多数のレコードを生成でき、ACTIONS ALLには含まれないことに注意してください。ライフサイクル・イベントを監査する必要がある場合に明示的に指定します。デプロイメントのセキュリティおよびコンプライアンス要件に従って、監査アクションおよび保持を選択します。SDKアプリケーション・ログは診断であり、データベース監査証跡にかわるものではありません。

Oracle Deep Data Security Operationsの監査およびDeep Sec監査可能なアクションの公式リストを参照してください。

取消時間契約

データベース・ポリシーの取消しとOCI IAMグループ・メンバーシップの削除の有効時間は異なります。

管理アクション 有効期間
revoke_agent_memory_policies()のコール このファンクションは、ストア固有のデータベース割当てを削除し、コミットしてから戻ります。その後の保護されたデータベース・ステートメントは、そのポリシーを受信しなくなります。すでに実行されている文は遡及的に取り消されません。
OCI IAMの権限受領者グループからのユーザーの削除 新しく発行されたアクセス・トークンは、更新されたメンバーシップを反映します。ユーザーにすでに発行されているアクセス・トークンには、そのgroupクレームが引き続き含まれており、そのトークンが期限切れになるまで、対応するDeep Secデータ・ロールの認可を続行できます。

したがって、IAMのみの取消しの有効上限は、発行されたトークンのexpクレームの残りの存続期間です。OCI IAMアクセス・トークンの存続期間は構成可能です。リソース・アプリケーション、ユーザー・セッションまたはカスタム有効期限が設定されていない場合、ドキュメント化されたデフォルトは3600秒です。アプリケーションは、期限切れのトークンの再利用を停止し、現在のメンバーシップを反映する要求を持つ新しいトークンを取得する必要があります。

緊急失効の場合、最初にrevoke_agent_memory_policies()をコールして後続の文のデータベース割当てを即時に削除してから、OCI IAMグループからユーザーを削除します。データベース・ポリシーを再付与するのは、グループ全体がアクセスを回復する必要がある場合のみです。グループが認可されている間に1つのメンバーのみを削除する必要がある場合は、トークンの有効期限に依存するか、デプロイメント固有の短いアクセス・トークンの存続期間および再認証ポリシーを使用します。

前述のDeep Secセキュリティ・コンテキスト・ライフサイクル参照とともに、OCI IAMのAPIを使用した認可の管理およびトークン有効期限表を参照してください。