文档中心

智能体身份和权限管理平台

权限管控

权限管理综合用户指南

Overview

权限管理服务核心目标是把“谁可以对什么资源执行什么操作”沉淀为可管理、可校验、可查询的授权策略。服务通过 Cedar policy 对 principal、action、resource 和原始调用方链路进行 allow/deny 决策，并为权限网关和业务服务提供统一鉴权入口。

一个典型接入流程是：先创建权限空间，再注册资源和动作，随后通过策略或快捷授权建立权限关系，最后在运行时调用鉴权接口。需要展示权限、排查授权或做列表过滤时，可使用主体权限反查和对象权限反查接口。

如果您是业务管理员，重点关注权限空间、资源动作、策略和权限点的配置顺序。

如果您是服务研发，重点关注 CheckPermission、CheckPermissionWithToken、IsAuthorized 和 References 的传参语义。

如果您是权限网关使用者，重点关注资源类型、动作 key、权限空间和策略状态是否与网关路由保持一致。

核心概念与对应 API

权限空间 Namespace

权限空间是 policy、resource、action 和 permission point 的归属边界，通常对应一个业务、产品线、租户或环境。NamespaceName 是账号内可读名称，默认可使用 default；NamespaceId 是内部稳定 ID。

模块能力

隔离不同业务或环境的授权数据，避免策略、资源和动作互相污染。

承载资源树、动作列表、权限点和策略列表的统一查询入口。

作为管理面对象定位的优先字段，与业务 key 组合使用。

API

API Action	用途
CreateNamespace	创建新的权限空间。
GetNamespace	按 NamespaceName 或 NamespaceId 查询权限空间详情。
ListNamespaces	分页检索权限空间，可用于控制台列表。
UpdateNamespace	更新权限空间展示信息。
DeleteNamespace	删除权限空间；删除前应确认资源、动作、策略和权限点的依赖关系。

资源模型 Resource

资源表示被访问对象，例如知识库、文档、数据库集合、模型、项目或工作流。资源由 ResourceType 和 ResourceKey 共同表达，支持父子层级和资源树查询。

模块能力

在权限空间内维护资源 key、资源名称、资源类型、父资源关系和启停状态。

通过 ParentResourceKey 维护资源树路径，支持按根节点和深度查询。

通过 Enabled 控制资源是否参与业务侧展示或治理流程。

API

API Action	用途
CreateResource	在指定权限空间内创建资源。
GetResource	按 NamespaceName 和 ResourceKey 查询资源。
ListResources	按资源类型、父资源、启停状态分页查询资源。
UpdateResource	更新资源名称、父资源、描述、属性或启停状态。
DeleteResource	删除资源。
GetResourceTree	按资源类型、根节点和深度查询资源树。

典型规则

ResourceKey 在权限空间内应稳定可读，不允许包含 /。

资源树路径由父子关系维护，不建议业务方自行拼接为策略判断依据。

创建时 Enabled 默认可按业务规则置为 true；如需冻结资源，可通过更新接口显式关闭。

动作模型 Action

动作表示主体可以对某类资源执行的操作，例如 read、write、delete、search 或业务自定义动作。动作通常与权限网关路由的 ActionValue 保持一致。

模块能力

在 ResourceType 下维护可授权动作。

通过启停状态控制动作是否可用于控制台选择和治理。

为策略编写、快捷授权、权限反查和权限网关 APISpec 提供统一词表。

API

API Action	用途
CreateAction	在指定资源类型下创建动作。
GetAction	按 ActionId 或 NamespaceName + ResourceType + ActionKey 查询动作。
ListActions	按资源类型和启停状态分页查询动作。
UpdateAction	更新动作描述或启停状态。
DeleteAction	删除动作。

典型规则

ActionKey 不允许包含 /。

动作 key 一旦被策略、网关路由或业务代码依赖，应避免直接改名；需要变更时先新增再迁移。

策略与快捷授权 Policy

策略是最终参与 Cedar 引擎判定的授权规则。策略包含 effect、principal、operation、resource、condition 等表达式；状态为 ENABLE 时参与鉴权，状态为 DISABLE 时不参与授权决策。

模块能力

创建、校验、查询、更新和删除 Cedar policy。

通过 GrantPermission 快速生成常见主体到资源动作的授权关系。

支持 permit 和 forbid；运行时最终结果以 Cedar 引擎判定为准。

API

API Action	用途
CreatePolicy	创建策略。
ValidatePolicy	校验策略语法和结构，建议在发布前调用。
GetPolicy	查询策略详情。
ListPolicies	分页查询策略，可按状态、名称等条件过滤。
UpdatePolicy	更新策略定义、描述或状态。
DeletePolicy	删除策略。
GrantPermission	使用封装参数生成常见授权策略。

校验顺序

确认 NamespaceName 存在。

确认策略中的主体、动作和资源表达式符合业务模型。

调用 ValidatePolicy 校验 Cedar policy。

创建策略并保持 Status=ENABLE，或先以 DISABLE 保存草稿。

使用测试主体调用鉴权接口，验证 allow/deny 是否符合预期。

权限点 Permission Point

权限点把业务中的鉴权位置注册到权限空间，例如某个页面按钮、后端接口、工作流节点或网关路由。权限点可配置为强拦截或宽松观察模式。

模块能力

按 NamespaceName 与 AuthPointId 唯一定位业务鉴权点。

维护权限点名称、链接、启停状态和决策模式。

支持从 PERMISSIVE 观察模式逐步切换到 ENFORCE 强拦截模式。

API

API Action	用途
CreatePermissionPoint	创建权限点。
GetPermissionPoint	按 PermissionPointId 或 AuthPointId 查询权限点。
ListPermissionPoints	按类型、名称、启停状态分页查询权限点。
UpdatePermissionPoint	更新权限点名称、链接、启停状态或决策模式。
DeletePermissionPoint	删除权限点。

决策模式

DecisionMode	含义	适用阶段
ENFORCE	严格执行拒绝结果，请求无权限时阻断。	正式上线后
PERMISSIVE	拒绝结果可转换为允许，并在 message 中标记 permissive。	灰度、观察和策略调试

运行时鉴权

运行时鉴权把一次访问请求转换为主体、动作、资源、上下文和引用关系，再交给策略引擎判定。业务服务可直接传主体，也可通过 token 解析主体。

模块能力

支持直接鉴权、权限封装鉴权和 token 鉴权。

支持 References 表达主体或资源父实体关系，例如用户属于团队、文档属于空间。

支持 OriginalCallers 描述上游调用链，便于区分直接访问和代理访问。

API

API Action	用途
IsAuthorized	Core 鉴权接口，按主体、动作、资源和上下文返回授权结果。
CheckPermission	面向 API 模块封装后的权限检查接口。
CheckPermissionWithToken	基于 token 解析主体后做权限检查。
BatchCheckPermissionWithToken	内部批量 token 鉴权接口，适合网关或插件批量场景。

请求建模

Subject：访问发起方，使用 Type 和 Id 表达。

Action：当前访问动作，应与动作模型中的 ActionKey 对齐。

Resource：当前访问对象，应与资源模型中的 ResourceKey 对齐。

Context：运行时上下文，例如环境、来源、请求属性等。

References：主体或资源的父实体关系，用于 Cedar 关系判断。

权限反查

权限反查用于回答“某个主体拥有哪些权限”或“某个对象对哪些主体开放”。它主要服务于权限展示、排障、列表过滤和运营分析。返回内容是策略投影，不等同于完整运行时授权判定。

模块能力

批量查询主体维度的权限投影，支持每次最多 100 个 task。

批量查询对象维度的权限投影，支持按主体类型、动作、对象类型和 effect 过滤。

默认只返回 permit；需要排查 forbid 时必须显式传入 Filter.Effects。

API

API Action	用途
BatchGetSubjectPermissions	查询主体命中的 action/resource 投影。
BatchGetObjectPermissions	查询对象命中的 subject/action 投影。

查询规则

顶层使用 NamespaceName 加 Tasks 批量查询。

任一 task 参数非法时按请求错误返回，不做部分成功。

wildcard 投影以 Type=any、Id=any 形式返回并参与过滤。

带 Cedar condition 的策略只有在 task 显式包含 conditional policy 时返回，并携带 condition 文本。

标签、项目与配额

标签、项目和配额用于治理权限资源、控制台筛选和容量确认。它们不是授权决策的核心输入，但会影响资源管理、展示和创建前检查。

API

API Action	用途
TagResources	为资源绑定标签。
UntagResources	解除资源标签。
ListTagsForResources	查询资源标签或按标签过滤资源。
GetQuotaConfirm	确认服务码、配额码和维度下的配额。

模块关系与职责边界

模块	负责什么	不负责什么
权限空间	隔离一组授权对象和策略。	不表达具体业务资源层级。
资源与动作	提供授权词表和对象模型。	不直接决定 allow/deny。
策略	表达最终授权规则。	不负责资源发现和 token 解析。
权限点	登记业务鉴权入口和执行模式。	不替代策略内容。
鉴权接口	根据请求和策略返回判定结果。	不创建缺失的资源、动作或策略。
权限反查	按策略投影返回可展示或可排查的权限关系。	不等同于一次带上下文的完整鉴权。
权限网关	把 HTTP 请求映射为权限管理可识别的主体、动作和资源。	不直接维护授权策略。

使用流程

流程一：从零配置权限空间并完成一次鉴权

创建权限空间。

调用 CreateNamespace 创建业务独立的权限空间，记录 NamespaceName 和 NamespaceId。

注册资源模型。

调用 CreateResource 创建资源；如有父子关系，填入 ParentResourceKey 并用 GetResourceTree 检查结构。

注册动作模型。

调用 CreateAction 为资源类型创建动作 key，例如 read、write、delete 或业务自定义动作。

创建策略。

使用 CreatePolicy 写入 Cedar policy，或用 GrantPermission 生成常见授权。

校验策略。

调用 ValidatePolicy 确认策略语法和结构无误。

发起鉴权。

调用 CheckPermission 或 IsAuthorized，传入主体、动作、资源、上下文和引用关系。

核对结果。

如果结果不符合预期，先检查策略状态是否为 ENABLE，再检查资源 key、动作 key 和引用关系。

流程二：反查主体或对象权限

选择查询方向。

需要看“用户有什么权限”时使用 BatchGetSubjectPermissions；需要看“资源对谁开放”时使用 BatchGetObjectPermissions。

组装任务。

在同一个 NamespaceName 下提交 task，单次最多 100 个。

设置过滤。

按动作、对象类型、主体类型或 effect 过滤；不传 effect 时默认只看 permit。

解释结果。

把返回结果理解为策略投影。涉及上下文条件、动态属性或业务侧额外限制时，应再调用运行时鉴权确认。

场景选择指南

场景	推荐能力	说明
新业务首次接入权限系统	Namespace + Resource + Action + Policy	先建立稳定词表，再配置授权关系和鉴权入口。
已有服务只需要一次性授权	GrantPermission	适合常见主体到资源动作的授权，不适合复杂条件策略。
需要表达继承关系	References + Cedar relation	例如用户属于团队、文件属于目录、对象属于项目。
策略上线前做语法检查	ValidatePolicy	创建或更新策略前先校验，减少线上拒绝异常。
灰度接入鉴权点	Permission Point + PERMISSIVE	先观察拒绝影响面，再切换强拦截。
控制台展示用户权限	BatchGetSubjectPermissions	返回策略投影，适合列表展示和排查。
控制台展示资源授权对象	BatchGetObjectPermissions	适合对象详情页、共享成员页和管理后台。
API 流量统一接入权限	权限网关 + 权限管理	网关负责抽取请求资源，权限管理负责策略判定。

常见问题

为什么创建了策略，鉴权仍然拒绝？

优先检查策略状态是否为 ENABLE。状态为 DISABLE 的策略不会参与授权决策。随后检查请求中的主体、动作、资源 key、资源类型和引用关系是否与策略表达式一致。

资源 key 或动作 key 可以包含路径分隔符吗？

不可以。ResourceKey 和 ActionKey 均不允许包含 /。如果业务资源天然是路径，建议把路径作为属性或独立字段保存，将稳定短 key 作为授权标识。

权限反查结果能直接代表运行时鉴权结果吗？

不能。权限反查返回的是命中策略的投影，默认只返回 permit。运行时鉴权还会受到上下文、引用关系、条件策略、forbid 规则和权限点模式影响。

权限管理和权限网关如何配合？

权限管理维护权限空间、资源、动作和策略；权限网关维护服务、路由和 APISpec。一次请求进入网关后，网关抽取资源标识和动作，再调用权限管理获得最终 allow/deny 结果。

最近更新时间：2026.08.24 15:15:46

这个页面对您有帮助吗？

有用

无用