权限网关基于火山引擎的 API 网关（APIG）构建，为您提供一种无侵入式的全链路权限管控方案。它专门解决`User -> Agent -> Tool`调用链路中的权限校验难题，让你无需修改业务代码，即可实现统一、细粒度的权限控制。本指南将引导你完成从创建权限网关服务、配置路由规则到最终发布的全过程，帮助你快速为你的服务接入自动化、高安全性的权限保护。 ## 核心价值 * **无侵入式集成**：所有流向你后端服务的请求都会被网关自动拦截并执行权限校验，无需你的业务代码进行任何改造或集成 SDK。 * **多身份协同校验**：能够同时识别和校验调用链路中的用户身份、智能体身份，并关联目标资源权限，实现端到端的安全闭环。 * **集中化策略管理**：通过关联预设的**权限空间**，你可以使用统一的 Cedar 策略来定义所有路由和资源的访问规则，实现“谁能通过谁操作什么”的精准控制。 ## 工作原理 1. **流量劫持**：你将获得一个专属的**劫持域名**。所有指向你后端服务的请求都通过此域名进入权限网关。 2. **策略关联**：每一个网关服务都会绑定一个**权限空间**，该空间内包含了预先定义好的 Cedar 权限策略。 3. **自动校验**：当请求到达网关时，系统会自动解析请求中的用户身份、智能体身份以及请求的资源信息，并与权限空间中的策略进行匹配。 4. **智能放行/拒绝**：如果匹配成功且策略允许，请求将被转发至你的后端服务；否则，请求将被直接拒绝。整个过程对你的业务应用完全透明。 ## 前提条件你已开通智能体身份和权限管理平台服务并完成授权。详情请参见[开通智能体身份和权限管理平台并完成授权](https://www.volcengine.com/docs/86848/2123358)。 ## 步骤一：创建权限网关服务首先，你需要创建一个权限网关服务，它将作为你后端服务的安全代理。 1. 登录[火山引擎智能体身份和权限管理平台](https://console.volcengine.com/identity)。 2. 在左侧导航栏，选择**权限管控** \> **权限网关**。 3. 在页面右上角，单击**新建服务**。 4. 在**新建服务**表单中，配置以下信息： * **服务名称**：为你的服务指定一个唯一的名称，如 `trip-agent-gateway`。 * **后端服务类型**： * **自定义**：如果你的后端服务是任意 HTTP/HTTPS 服务，请选择此项，并填写 **后端服务域名**、端口和超时时间。 * **VikingDB**：如果你的后端是火山引擎的内置服务，可直接从下拉列表中选择。 * **关联权限空间**：选择一个已创建的 **权限空间**。所有流经此网关的请求，都将使用该空间内的策略进行校验。你也可以点击 **创建权限空间** 快速创建一个。 * **描述/所属项目/标签**：填写可选信息，以便于分类和管理。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/9dec9ff97d2648eb869633746d17c4e3) 4. 单击**确定**保存。此时，服务状态为**未发布**。 ## 步骤二：配置路由规则路由规则定义了哪些 API 请求需要被权限网关拦截并进行校验。你可以通过自动解析或手动配置两种方式来创建路由。 1. 在权限网关列表中，单击目标服务名称，进入其详情页。 2. 在详情页中，单击**新建路由**。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/cc8aac495502482b812056208d583376) 3. 配置路由信息。系统提供两种配置方式：**自动解析**和**手动配置**。自动解析通过上传 API 文档，系统可以自动为你生成路由规则，极大提升配置效率。 1. 在配置方式中，选择**自动解析**。 2. 选择你的**文档类型**，支持 OpenAPI/Swagger 或自然语言描述（Markdown/Word/TXT）。 3. **上传文件**：单击上传你的 API 文档。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/41ee9513e57d4df09e08e501a2b5c385) 上传并解析成功后，路由列表将自动填充从文档中识别出的所有 API 接口。手动配置如果你需要定义更复杂的路由，或者没有 API 文档，可以选择手动配置。 1. 在配置方式中，选择 **手动配置**。 2. 填写路由信息： * **路由名称**：为该路由指定一个唯一的名称，如 `查询知识库`。 * **请求方法**：选择此路由匹配的 HTTP 请求方法，如 GET、POST 等。 * **接口路径**：填写 API 的路径，支持路径变量，如 `/api/documents/{docId}`。 * **匹配类型**：选择 **前缀匹配**（如 `/api/*`）或 **精确匹配**。 3. **配置关联资源**：这是权限校验的核心。你需要告诉网关如何从请求中提取用于鉴权的资源 ID。 * **资源类型**：输入资源的类型，如 `knowledge_base` 或 `document`。此类型必须与权限空间中 Cedar 策略定义的资源类型一致。 * **位置**：选择资源 ID 存在于请求的哪个部分，如 Header、Body 或 Path。 * **字段名**：使用 JSONPath 语法指定资源 ID 的具体位置，如 `$.data.items[*].id`。 * **是否作为鉴权对象**：勾选此项。网关将使用提取到的资源 ID 与 Cedar 策略中的 `resource` 字段进行匹配。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/5cc3a6ef2f4945c5a7ba75b5379fe7f2) 4. 单击**创建**保存路由。此时，路由状态为“未启用”，服务整体状态变为 **草稿**。 ## 步骤三：发布服务完成所有路由配置后，你需要发布服务，使权限规则正式生效。 1. 在服务详情页的右上角，单击**发布服务**。 2. 在弹出的确认对话框中，再次单击 **发布**。 3. 发布成功后，服务状态将变为**运行中**。此时，所有通过该网关**劫持域名**的请求都将自动执行权限校验。 ## 结果与验证 * **服务列表**：在**权限网关**列表页，你可以看到所有服务的状态、劫持域名、关联的权限空间等关键信息。 * **服务详情**：你可以随时进入服务详情页，查看或在服务**停用**状态下编辑路由规则。 * **生效逻辑**： * 只有**运行中**的服务，其权限规则才真正生效。 * **未发布** 或 **草稿** 状态的服务，仅保存了配置，不会对线上流量产生任何影响。 * 如需修改已在运行的服务的路由，必须先**停用服务**，修改后再重新**发布**。 ## 常见问题 ### **为什么路由自动解析失败？** 请检查你上传的 API 文档是否包含了清晰的接口定义，至少需要包含**请求方法 (Method)** 和 **路径 (Path)** 。如果文档格式不规范，建议切换到**手动配置**。 ### **服务已发布，但权限校验不生效？** * 请重点排查以下两点： * **策略是否存在**：检查关联的**权限空间**中，是否编写了针对目标资源的 `permit` 或 `forbid` 策略。 * **资源映射是否正确**：在路由的 **关联资源** 配置中，检查 **资源类型**、**位置** 和 **字段名 (JSONPath)** 是否能准确地从请求中提取出资源 ID。 ### **服务无法发布，提示“权限空间未关联”？** 每个权限网关服务都必须关联一个权限空间。请在服务配置中，选择一个已经创建好的权限空间。如果还没有，请先前往**权限策略**模块创建一个。

AgentKit