> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 密钥与连接管理

> 使用版本化 Secret 管理外部资源连接凭据。

UOSE系统通过 Secret Manager 管理外部资源连接。resource 不直接保存密码、token 或证书，而是保存一个不可变 Secret 版本引用。这样可以把资源配置和敏感凭据分离，并支持凭据轮换。

## Connection Ref

资源通过 `connectionRef` 引用 Secret 版本。常见形式如下：

```text theme={null}
secret://sap%2Fprod%2Fmain?version=1
```

引用中包含：

* Secret key：逻辑密钥名称。
* Version：不可变版本号。

当 Secret 更新时，系统创建新版本，不覆盖旧版本。resource 只有更新到新 `connectionRef` 后才会读取新凭据。

## Secret Payload

不同资源类型需要不同 payload。常见字段包括：

* `baseUrl`：源系统服务根地址。
* `authMode`：认证方式，例如 `current_user_oidc`、`basic`、`static_bearer`、`api_key`。
* `username`、`password`、`token`、`apiKey`：不同认证模式下的凭据。
* `headers`：固定请求头，敏感头会被过滤。
* `queryParams`：源系统要求的固定查询参数。
* `tls`：私有 CA、SNI 或证书校验配置。
* `timeoutMs`：源系统请求超时。

Secret payload 必须只放连接相关内容，不应放业务策略或同步范围。这些应放在 resource capabilities 中。

## 当前用户凭据

部分资源支持 `current_user_oidc`。这种模式使用当前请求用户的 OIDC token 回源访问外部系统，适合需要继承用户权限的场景。

使用时要注意：

* REST 调用可复用当前登录用户 token。
* MCP 场景需要显式转发业务用户 token。
* 后台队列不能长期依赖短期用户 token。
* 审计中应记录 actor 与任务上下文，不能把 token 写入日志。

如果资源需要稳定后台同步，优先使用静态 API key、服务账号或源系统授权 token。

## 版本化轮换

推荐轮换流程：

1. 从现有 Secret 版本载入草稿。
2. 更新 token、密码或证书。
3. 保存为新版本。
4. 在资源设置中把 `connectionRef` 更新到新版本。
5. 触发一次同步或连接验证。
6. 确认新版本可用后，再按组织流程停用旧凭据。

版本化设计让线上资源不会因为编辑草稿而立即受影响。

## 安全边界

UOSE 对密钥管理的原则是：

* Secret payload 不进入 ontology snapshot。
* password、token、username 等敏感字段不写入 RDF、实体属性或日志。
* resource 页面只展示 `connectionRef`，不展示明文凭据。
* TLS 放宽配置仅用于临时排障，不建议长期生产使用。
* 连接信息应按资源和环境拆分，避免多个生产资源共用同一高权限密钥。