第13章 凭据存储 · Omnigent

Credential Store

Omnigent 服务器支持将每个用户的集成凭据加密并持久化存储。加密由可插拔的密码后端处理，每个服务器可独立选择。系统内置两种后端：

• AWS KMS — 适用于部署在 AWS 上的环境。
• HashiCorp Vault Transit — 提供厂商无关的替代方案，适用于未部署在 AWS 上的环境。

每个密钥都绑定到其所属身份——（workspace_id, user_id, provider, account_id）——因此，已存储的凭据仅能在相同身份下解密。AWS KMS 通过加密上下文来强制实施此绑定；Vault Transit 则通过派生密钥实现。若未配置任何后端，凭据存储功能将处于禁用状态。

选择后端

设置 OMNIGENT_CREDENTIAL_CIPHER 以明确指定后端：

一旦设置了选择器，所选后端对应的密钥环境变量即为必需项——若环境变量不匹配，系统将抛出异常而非静默禁用存储；未知取值同样会抛出异常。

若未设置 OMNIGENT_CREDENTIAL_CIPHER，系统将自动检测并启用唯一配置的后端，作为零配置体验的便利功能。若未设置选择器却配置了多个后端，这将视为错误（系统不存在静默优先级机制）；若未配置任何后端，则凭据存储功能被禁用。

两个 SDK —— KMS 用的 boto3 和 Vault 用的 hvac —— 均采用惰性导入，仅在选中对应后端时加载。后端无关的基础存储组件不依赖任何 SDK；使用某一种后端的部署环境无需安装另一种后端所需的依赖。

AWS KMS

安装额外依赖包，并将存储指向 KMS 密钥：

pip install 'omnigent[kms]'

boto3 从标准 AWS 环境变量解析 AWS 凭据和区域。只有在首次执行加密或解密操作时，才会导入 SDK 或发起 AWS 调用。

HashiCorp Vault Transit

安装额外依赖包，并将存储指向 Vault Transit 密钥：

pip install 'omnigent[vault]'

Transit 密钥创建时必须设置 derived=true。身份级绑定依赖 Vault 派生特定上下文的密钥，因此非派生密钥无法强制实施此绑定。

读取与轮换

若在特定身份下无法读取密文——例如数据块错误或损坏、加密上下文不匹配——系统将降级为“重连”状态（受影响的集成被视为断开连接，直至重新连接），而非返回错误值。

全局存储配置错误会显式暴露，而非被掩盖。特别是，如果将 OMNIGENT_CREDENTIAL_VAULT_KEY 指向另一个密钥，Vault 后端会拒绝读取使用旧密钥写入的凭据，而不是将其视为用户断开连接——后者会导致系统使用错误密钥重新加密并覆盖仍可恢复的密文。