Skip to content
Muer

授权诊断

解决的问题

Section titled “解决的问题”

业务接口返回 403 IAM_ACCESS_DENIED 时，客户端不应该看到内部授权细节，但开发者和管理工具仍需要知道究竟是 Permission、Scope、Profile 还是身份域导致拒绝。

授权诊断使用真实 AuthorizationEngine 的决策结果，不在文档或前端重新实现一套授权逻辑。

关键概念

Section titled “关键概念”
  • AuthorizationDecision：(allowed, decisionCode, steps)；
  • AuthorizationDecisionStep：(code, passed, reason)；
  • 成功决策码：ALLOWED；
  • 常见拒绝码：PERMISSION_DENIED、SCOPE_DENIED、IDENTITY_DOMAIN_MISMATCH、CLIENT_TYPE_MISMATCH 以及 Profile 系列；
  • 接口：POST /iam/authorization/diagnostics。

请求接口

Section titled “请求接口”
项目 内容
Method POST
Path /iam/authorization/diagnostics
Auth Bearer Token
成功 HTTP 200，返回 AuthorizationDecision

该接口是 Authenticated Self Diagnostics：任意已认证 principal 都可以诊断 自己的授权决策，不要求任何 iam.admin.* permission；请求永远针对 SecurityContext 当前 principal，不能通过请求体指定他人。Admin Console 的 Diagnostics 页面是否展示由 capability iam.admin.diagnostics 控制 —— 页面展示与 API 访问条件是不同概念。

请求体示例：

{
  "permissionCode": "document:update",
  "domain": "EXAMPLE",
  "clientType": "WEB",
  "resourceType": "PROJECT",
  "resourceId": "101",
  "scopeAccess": "WRITE"
}

预期结果

Section titled “预期结果”

如果 Reader Profile 缺少 document:update，响应仍为 HTTP 200，但业务决策中：

allowed = false
decisionCode = PERMISSION_DENIED

steps 会给出授权引擎实际经过的判断步骤，适合后台诊断和排障。

使用边界

Section titled “使用边界”

面向普通业务客户端的 403 默认响应不会泄漏 Permission、Profile、Scope、Token 或完整决策步骤。详细诊断应只开放给受控的管理 / 排障场景。

源码

Section titled “源码”