深度数据安全

Oracle Agent Memory 与 Oracle Deep Data Security (Deep Sec) 集成，可在 Oracle AI Database 中强制执行最终用户授权。Deep Sec 是一项安全功能：其数据角色、数据授权和最终用户安全上下文决定了请求可以读取或修改哪些托管内存行。

重要提示：将此页上的 API 视为安全管理和请求安全接口。使用单独的数据库标识进行策略管理、托管模式所有权和运行时连接池。运行时池帐户不应具有提供对受保护的代理内存表的回退访问权限的直接权限。

Oracle Deep Data Security 概述介绍了数据库授权模型。有关完整的 OCI IAM 部署，请参阅使用深度数据安全性实施最终用户内存隔离。

安全模式

代理内存集成支持两个策略：

策略 有效访问权限
UserOwnRowsDeepDataSecurityPolicy 仅当用户范围代理内存行的所有者与 ORA_END_USER_CONTEXT.username 匹配时，才读取和写入用户范围代理内存行。内存链接读取要求两个端点内存在分配的策略下都可读；链接写入要求两个端点内存都属于该用户。
GlobalMemoriesDeepDataSecurityPolicy 读取 user_id 为 NULL 的未限定内存行。此策略不授予对其他用户的范围存储器的写入或访问权限。当两个端点内存都可以在活动策略下读取时，它会公开内存链接。只有此策略，两个端点必须是全局内存；当与自己的行策略结合使用时，拥有内存和全局内存之间的链接也是可见的。

策略对象是管理 API 的不透明选择。其托管表、数据角色、数据授权和 SQL 实施保持专用状态，以便 Oracle Agent Memory 可以安全地发展其数据库方案。不支持定制策略子类；请使用上面的两个策略类之一。

政策适用于 owner_schema 与 memory_store_id 的组合。为一个存储创建或分配策略不会将其分配给另一个存储，包括在其他所有者方案中具有相同 ID 的存储。

UserOwnRowsDeepDataSecurityPolicy 策略还按列限制写入。最终用户可以在插入自有行时设置身份列和所有权列，但以后不能更改这些列。策略授予以下写入表面：

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 组的映射数据角色还必须有权访问数据库驻留模型。按照 Use an in-database embedding model with Deep Sec 中所述在处理请求之前配置该访问权限。

OracleDBEmbedder 还可以通过 DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING 使用远程提供程序。该配置不使用数据库驻留模型，也不需要 SELECT ON MINING MODEL。分别配置远程提供商的 Oracle 凭证和网络访问。代理内存操作仍必须在 OracleMemoryEndUserSecurityContext 内运行。

管理调用在返回之前提交其数据库更改。有关底层角色和授权概念，请参阅 Oracle 的数据访问控制配置。

上下文使用检查

在受保护的应用程序工作运行之前，SDK 会拒绝不安全的组合：

这些检查诊断出错误的 SDK 执行路径。Oracle AI Database 数据授权将保持授权边界，并继续确定已验证的最终用户可以访问哪些行和列。

策略

class oracleagentmemory.core.deepsec.DeepDataSecurityPolicy

基准：object

确定支持的 Oracle Agent Memory Deep Data Security 策略。

策略对象是传递给 Deep Data Security 管理功能的不透明选择。实例化 UserOwnRowsDeepDataSecurityPolicy 或 GlobalMemoriesDeepDataSecurityPolicy。策略实施详细信息（包括托管表、数据角色、数据授权和 SQL）对 Oracle Agent Memory 保持专用，并且可能会在发行版之间发生更改。

此类不是自定义策略扩展点。管理功能会拒绝 Oracle Agent Memory 提供的两个策略类以外的子类。

示例

为最终用户行和未定义的全局内存创建策略集：

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

class oracleagentmemory.core.deepsec.UserOwnRowsDeepDataSecurityPolicy

基础：DeepDataSecurityPolicy

授予对已验证最终用户拥有的行的访问权限。

此策略为用户拥有的数据授予行范围 SELECT、列范围 INSERT 和 UPDATE 以及行范围 DELETE。所有权列、记录类型列、生成的列、创建时间和保留列在插入后无法更改。可以插入和删除记录块，但无法更新，因为 SDK 会将它们替换为完整行。该策略还授予初始化运行时存储所需的注册表读取权限。内存链接 SELECT 遵循共享端点可见性规则，而链接 INSERT、UPDATE 和 DELETE 要求两个端点内存都属于最终用户。

示例

policy = UserOwnRowsDeepDataSecurityPolicy()

class oracleagentmemory.core.deepsec.GlobalMemoriesDeepDataSecurityPolicy

基础：DeepDataSecurityPolicy

授予对全局记忆的读取访问权限以及可见记忆之间的链接。

此策略对 user_id 为 NULL 的内存行授予 SELECT，并授予初始化运行时存储所需的注册表读取权限。当最终用户根据分配的 Deep Data Security 策略可读取两个端点内存时，其内存链接读取授权会公开一个链接。因此，只有此策略，这两个端点必须是全局内存；结合自己的行策略，拥有内存和全局内存之间的链接也是可见的。它不允许写入或访问其他用户的范围存储器。

示例

policy = GlobalMemoriesDeepDataSecurityPolicy()

主用户

分配目标可以是访问令牌的 group 自定义声明中包含的 OCI IAM 组，也可以是本地深层安全最终用户。必须先将 OCI IAM 组信息配置为定制声明，然后 Oracle AI Database 才能将其映射到外部数据角色。请参阅在 OCI IAM 中配置组信息的定制声明。

class oracleagentmemory.core.deepsec.Principal

基准：object

用于标识接收代理内存策略分配的人员的基本类型。

主用户是 grant_agent_memory_policies() 或 revoke_agent_memory_policies() 确定的安全身份。主体标识其深度数据安全数据角色或数据授予对特定代理内存存储的控制访问权限的被授权者。支持的当前主用户类型包括 OCI IAM 组和本地数据库最终用户。

将 OciGroupPrincipal 用于 OCI IAM 组，将 LocalEndUserPrincipal 用于数据库管理的深度数据安全最终用户。不支持将直接 Principal 实例传递到管理函数。

class oracleagentmemory.core.deepsec.OciGroupPrincipal

基础：Principal

确定接收代理内存策略的 OCI IAM 组。

class oracleagentmemory.core.deepsec.LocalEndUserPrincipal

基础：Principal

确定本地 Deep Data Security 最终用户接收策略。

管理

通过专用安全管理连接运行这些功能。对于跨方案代理内存表，该帐户需要适用的深度安全管理权限（包括 CREATE ANY DATA GRANT、DROP ANY DATA GRANT 和 ADMINISTER ANY DATA GRANT），以及创建和删除数据角色的权限。不要将这些权限授予运行时池帐户。

oracleagentmemory.core.deepsec.add_deep_data_security_policies

为代理内存策略创建数据角色和数据授权。

策略的范围为 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 的最终用户安全上下文；有关验证、角色解析、连接重用和上下文清理，请参见数据库服务器如何管理最终用户安全上下文。

class oracleagentmemory.core.deepsec.OracleMemoryEndUserSecurityContext

基准：object

将 Oracle 最终用户安全上下文应用于代理内存操作。

输入此上下文管理器将使 security_context 可用于当前执行上下文中使用的 Oracle 支持的代理内存存储。每个数据库操作在获取其物理连接后应用上下文，验证最终用户身份是否处于活动状态，并在释放连接之前清除上下文。此行为适用于直接连接和连接池。

范围将传播到等待的异步代理内存调用。超过 with 或 async with 块的调用方任务无法使用过期作用域。块内接受的后台内存提取作业保留专用快照，因此它们可以在块退出后完成。

当最终用户或数据库访问令牌发生更改时，请使用全新的 oracledb.EndUserSecurityContext。Oracle AI Database 从提供的令牌中的声明派生启用的数据角色；此管理器不刷新、撤销或检查 OAuth 令牌。

注释

此类对 Oracle Agent Memory 操作进行限定。它不会修改应用程序 SQL 在 SDK 外部直接使用的任意连接。支持嵌套，包括嵌套相同的管理器实例；每个出口从其匹配条目恢复上下文。

示例

将 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__（异步）

退出异步作用域而不隐藏块异常。

method（方法）__enter__

输入范围并返回此上下文管理器。

在当前执行上下文中启动的代理内存操作使用此管理器的最终用户安全上下文，直到匹配退出。

method __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。数据库管理员可以为深层安全配置操作创建统一审计策略，例如创建或删除数据角色和数据授权，授予或撤消数据角色，以及创建或删除最终用户和最终用户上下文。审计记录可通过 UNIFIED_AUDIT_TRAIL 获取，并且可以包括最终用户安全上下文下执行的活动的最终用户身份和安全上下文标识符。

CREATE END USER SECURITY CONTEXT 操作记录安全上下文创建。Oracle 指出，它可以生成许多记录，并且不由 ACTIONS ALL 包括；在必须审计该生命周期事件时明确指定该记录。根据部署的安全性和合规性要求选择审计操作和保留。SDK 应用程序日志是诊断日志，不能替代数据库审计线索。

请参阅 Audit Oracle Deep Data Security Operations 和 Deep Sec Auditable Actions 的官方列表。

撤消时间合同

数据库策略撤销和 OCI IAM 组成员资格删除的有效时间不同：

管理活动 有效期
致电 revoke_agent_memory_policies() 该函数会在返回之前删除特定于存储的数据库分配和提交。后续受保护的数据库语句不再接收该策略。尚未追溯取消已执行的对账单。
从 OCI IAM 中的被授权者组中删除用户 新发布的访问令牌反映更新的成员身份。已发给用户的访问令牌仍包含其 group 声明，并且可以继续授权相应的深层安全数据角色，直到该令牌到期。

因此，仅 IAM 撤销的有效上限是发行的令牌 exp 声明中的剩余生命周期。OCI IAM 访问令牌生命周期是可配置的；如果未设置资源应用程序、用户会话或自定义到期，则记录的默认值为 3600 秒。应用程序必须停止重复使用过期的令牌，并获取其声明反映当前成员资格的新令牌。

对于紧急撤销，请首先调用 revoke_agent_memory_policies() 以立即删除后续语句的数据库分配，然后从 OCI IAM 组中删除用户。仅当整个组应重新获得访问权限时，才重新授予数据库策略。如果在组保持授权状态时只能删除一个成员，请依赖令牌到期或使用特定于部署的更短访问令牌生命周期和重新验证策略。

请参阅 OCI IAM 的使用 API 管理授权和令牌到期表，以及上述深层安全上下文生命周期参考。