docs: clarify API principal isolation scope and direct_header risks

Document MCP OAuth-only principal boundaries and spoofing risks for
direct_header mode in API docs and the integrations settings UI.
This commit is contained in:
wizardchen
2026-06-30 11:18:19 +08:00
committed by lyingbug
parent 97bca74a31
commit 168b1d4cfe
6 changed files with 53 additions and 7 deletions
+23
View File
@@ -356,6 +356,29 @@ curl --location --request POST 'http://localhost:8080/api/v1/tenants/10000/api-k
}
```
## API Key Principal:隔离边界与安全说明
`api-principal-config` 控制 `X-API-Key` 请求如何映射为终端 **Principal**。请先理解以下边界,再选择模式。
### Principal 隔离范围(当前实现)
Principal **仅**用于按终端用户隔离以下能力:
- **MCP OAuth** 访问令牌(同一租户下不同外部用户各自授权,token 互不共用)
- 对话内 MCP OAuth 提示、MCP 工具审批等与 Principal 绑定的流程
Principal **不会**缩小 API Key 的 API 权限:`X-API-Key` 认证仍授予租户内 **Admin** 角色,知识库、会话、Agent 等接口**不按**外部用户做 RBAC 隔离。若需要全链路 per-user 权限控制,须在业务侧自行鉴权,不能仅依赖本配置。
### 模式与安全假设
| mode | 适用场景 | 安全假设 |
| ---- | -------- | -------- |
| `tenant` | 无 per-user MCP 需求 | 全租户共用一个 MCP OAuth 身份 |
| `direct_header` | 仅可信服务端到服务端 | 用户 ID 来自调用方请求头,**可被持有 API Key 的任意调用方伪造**(冒充其他外部用户并共用/劫持其 MCP OAuth 授权)。面向终端用户或不可信客户端时**禁止**使用;若必须使用,请开启 `require_direct_header` 并确保 API Key 仅保存在可信后端 |
| `signed_token` | 面向终端用户的集成(**推荐**) | 由业务后端使用 `hmac_secret` 为外部用户签发短期 HS256 JWT;无效或缺失 token 返回 401,**不回退**为租户级 Principal |
`direct_header` 模式下,若未携带用户 ID 请求头:`require_direct_header=false` 时回退为租户级 Principal;`require_direct_header=true` 时返回 401。
## GET `/tenants/:id/api-principal-config` - 获取 API Key 用户身份配置
返回租户级 API Key 请求如何映射为终端 Principal 的配置。**需要 Owner 权限**。
+6 -1
View File
@@ -5756,11 +5756,16 @@ export default {
apiKey: 'Tenant API Key',
apiKeyDesc: 'The API key is still tenant-level. User identity is supplied by the principal mode below.',
principalMode: 'User identity mode',
principalModeDesc: 'Controls how X-API-Key requests map to a principal for OAuth MCP tokens and other per-user features.',
principalModeDesc:
'Controls how X-API-Key requests map to a principal. Today this principal only isolates MCP OAuth and related flows; it does not reduce the tenant-admin API scope of the API key.',
principalScope:
'Principal isolation applies to MCP OAuth tokens and in-chat MCP authorization only. The API key still has tenant-admin API access; knowledge bases, sessions, and other resources are not isolated per external user.',
modeTenant: 'Tenant only',
modeDirect: 'Direct user ID',
modeSigned: 'Signed token',
directWarning: 'Direct user ID trusts the caller-supplied header. Use only for trusted server-to-server calls.',
directWarningDetail:
'Anyone with the API key can change the user ID header to impersonate another external user and reuse or hijack that user\'s MCP OAuth authorization. Do not use this from browsers or untrusted clients; use Signed token for end-user apps.',
signedRecommended: 'Recommended for user-facing apps: your backend signs a short-lived HS256 JWT for the external user.',
directHeader: 'User ID header',
requireDirectHeader: 'Require user ID header',
+6 -1
View File
@@ -5767,11 +5767,16 @@ export default {
apiKey: "테넌트 API Key",
apiKeyDesc: "API Key는 계속 테넌트 단위입니다. 사용자 ID는 아래 모드로 전달합니다.",
principalMode: "사용자 ID 모드",
principalModeDesc: "X-API-Key 요청을 Principal로 매핑하는 방식입니다. OAuth MCP 토큰 및 사용자별 기능에 사용됩니다.",
principalModeDesc:
"X-API-Key 요청을 Principal로 매핑하는 방식입니다. 현재 Principal은 MCP OAuth 등 사용자별 기능만 분리하며, API Key의 테넌트 관리자 권한은 줄이지 않습니다.",
principalScope:
"Principal 분리는 MCP OAuth 토큰과 대화 내 MCP 인증에만 적용됩니다. API Key는 여전히 테넌트 관리자 API 권한을 가지며, 지식베이스·세션 등은 외부 사용자별로 분리되지 않습니다.",
modeTenant: "테넌트만",
modeDirect: "사용자 ID 직접 전달",
modeSigned: "서명 토큰",
directWarning: "직접 사용자 ID 모드는 요청 헤더를 신뢰합니다. 신뢰된 서버 간 호출에만 사용하세요.",
directWarningDetail:
"API Key를 가진 호출자는 사용자 ID 헤더를 바꿔 다른 외부 사용자를 가장하고 해당 사용자의 MCP OAuth 인증을 공유하거나 탈취할 수 있습니다. 브라우저나 신뢰할 수 없는 클라이언트에는 사용하지 마세요. 최종 사용자 앱에는 서명 토큰을 사용하세요.",
signedRecommended: "사용자 대상 앱에는 권장됩니다. 비즈니스 백엔드가 외부 사용자용 단기 HS256 JWT를 서명합니다.",
directHeader: "사용자 ID 헤더",
requireDirectHeader: "사용자 ID 헤더 필수",
+6 -1
View File
@@ -5589,11 +5589,16 @@ export default {
apiKey: 'API Key арендатора',
apiKeyDesc: 'API Key остаётся на уровне арендатора; идентификатор пользователя задаётся режимом ниже.',
principalMode: 'Режим идентификации пользователя',
principalModeDesc: 'Определяет, как запросы с X-API-Key сопоставляются с Principal для OAuth MCP и других per-user функций.',
principalModeDesc:
'Определяет, как запросы с X-API-Key сопоставляются с Principal. Сейчас Principal изолирует только MCP OAuth и связанные потоки и не сужает область API ключа уровня admin арендатора.',
principalScope:
'Изоляция Principal распространяется только на токены MCP OAuth и авторизацию MCP в чате. API key по-прежнему имеет доступ admin арендатора; базы знаний, сессии и другие ресурсы не изолируются по внешнему пользователю.',
modeTenant: 'Только арендатор',
modeDirect: 'Прямой ID пользователя',
modeSigned: 'Подписанный token',
directWarning: 'Прямой ID доверяет заголовку вызывающей стороны. Используйте только для доверенных server-to-server вызовов.',
directWarningDetail:
'Любой, у кого есть API key, может подменить заголовок ID пользователя, выдать себя за другого внешнего пользователя и переиспользовать или перехватить его авторизацию MCP OAuth. Не используйте в браузере или ненадёжных клиентах; для пользовательских приложений выбирайте подписанный token.',
signedRecommended: 'Рекомендуется для пользовательских приложений: ваш backend подписывает краткоживущий HS256 JWT для внешнего пользователя.',
directHeader: 'Заголовок ID пользователя',
requireDirectHeader: 'Требовать заголовок ID пользователя',
+6 -2
View File
@@ -5769,11 +5769,15 @@ export default {
apiKey: "租户 API Key",
apiKeyDesc: "API Key 仍按租户级管理;终端用户身份由下方模式提供。",
principalMode: "用户身份模式",
principalModeDesc: "决定 X-API-Key 请求如何映射为 Principal,用于 OAuth MCP token 和其他按用户隔离的能力。",
principalModeDesc: "决定 X-API-Key 请求如何映射为 Principal。当前 Principal 仅用于按用户隔离 MCP OAuth 等能力,不会缩小 API Key 的租户管理员权限。",
principalScope:
"Principal 仅隔离 MCP OAuth 令牌与对话内 MCP 授权;API Key 仍拥有租户内管理员级 API 权限,知识库、会话等资源不会按外部用户隔离。",
modeTenant: "仅租户",
modeDirect: "直接传用户 ID",
modeSigned: "签名 Token",
directWarning: "直接传用户 ID 会信任调用方请求头,仅建议用于可信服务端到服务端调用。",
directWarning: "直接传用户 ID 会信任调用方请求头,仅适用于可信服务端到服务端调用。",
directWarningDetail:
"任何持有 API Key 的调用方都可以通过修改用户 ID 请求头冒充其他外部用户,从而共用或劫持其 MCP OAuth 授权。请勿用于浏览器或不可信客户端;面向终端用户请使用「签名 Token」。",
signedRecommended: "推荐给面向用户的应用:业务方后端为外部用户签发短期 HS256 JWT。",
directHeader: "用户 ID 请求头",
requireDirectHeader: "必须携带用户 ID",
@@ -55,6 +55,8 @@
<p>{{ $t('integrations.api.principalModeDesc') }}</p>
</div>
<div class="mode-panel">
<t-alert theme="info" :message="$t('integrations.api.principalScope')" />
<t-radio-group v-model="form.mode">
<t-radio-button value="tenant">{{ $t('integrations.api.modeTenant') }}</t-radio-button>
<t-radio-button value="direct_header">{{ $t('integrations.api.modeDirect') }}</t-radio-button>
@@ -64,8 +66,10 @@
<t-alert
v-if="form.mode === 'direct_header'"
theme="warning"
:message="$t('integrations.api.directWarning')"
/>
>
<template #message>{{ $t('integrations.api.directWarning') }}</template>
{{ $t('integrations.api.directWarningDetail') }}
</t-alert>
<t-alert
v-if="form.mode === 'signed_token'"
theme="success"