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