策略文档格式¶

每个 Policy 实体包含一个以 PostgreSQL jsonb 格式存储的 document 字段。本页描述该文档的模式和评估语义。

模式¶

{
  "Version": "2024-01-01",
  "Statement": [
    {
      "Sid":        "<optional statement identifier>",
      "Effect":     "Allow | Deny",
      "Action":     ["<service>:<Action>", ...],
      "Resource":   ["<FRN pattern>", ...],
      "Condition":  {
        "<Operator>": {
          "<condition-key>": "<value> | [<values>]"
        }
      }
    }
  ]
}

字段¶

Version¶

可选的策略文档版本字符串（例如 "2024-01-01"）。保留用于未来的模式演进。

Statement¶

必需的顶层数组。如果缺失或为空，该策略不会产生任何匹配，实际上相当于无操作。

Sid¶

可选的人类可读语句标识符。在授权响应中作为 matchedStatement 返回，用于可追溯性。

Effect¶

必需。必须为 "Allow" 或 "Deny" （区分大小写）。

"Deny" 语句优先评估，且 始终优先于 "Allow" 语句。
如果没有语句匹配，结果为 默认拒绝 。

Action¶

必需。单个操作字符串或操作字符串数组。每个条目使用 service:Action 约定。匹配规则：

模式	匹配
`"devices:Read"`	仅精确匹配操作 `devices:Read`
`"devices:*"`	以 `devices:` 开头的任何操作
`"*"`	任何操作

Resource¶

必需。单个 FRN 字符串/模式或 FRN 字符串/模式数组。完整的通配符和匹配规则请参阅 FRN 规范。

特殊情况：单元素数组 ["*"] 或字符串 "*" 匹配任何资源。

Condition¶

可选对象。如果存在，所有运算符都必须通过，语句才算匹配（运算符之间为 AND 逻辑）。

每个运算符将条件键映射到期望值。值可以是单个字符串或字符串数组。

支持的运算符¶
运算符	语义
`StringEquals`	实际上下文值必须在期望列表中（精确匹配）。
`StringNotEquals`	实际上下文值不得在期望列表中。
`StringLike`	实际值必须匹配至少一个 glob 模式（`` 被转换为 `.` 以进行正则匹配）。
`Bool`	`actual.toString()` 必须在期望列表中（例如 `"true"` 或 `"false"`）。

条件键可以携带 dotid: 前缀，在上下文查找前会被去除。上下文键也会以 snake_case 形式进行尝试（例如 principalType 也会尝试 principal_type）。

未知运算符将被评估为 false 并产生警告日志。

示例¶

以下策略允许用户主体读取和列出设备，同时显式拒绝删除任何设备：

{
  "Version": "2024-01-01",
  "Statement": [
    {
      "Sid": "AllowDeviceRead",
      "Effect": "Allow",
      "Action": ["devices:Read", "devices:List"],
      "Resource": ["frn:*:devices:device/*"],
      "Condition": {
        "StringEquals": {
          "dotid:principalType": "user"
        }
      }
    },
    {
      "Sid": "DenyDeviceDelete",
      "Effect": "Deny",
      "Action": ["devices:Delete"],
      "Resource": ["frn:*:devices:device/*"]
    }
  ]
}

该策略的评估顺序：

首先检查 DenyDeviceDelete 语句（拒绝遍历）。如果请求的操作是对任何设备 FRN 执行 devices:Delete，则立即返回 DENY 。
接下来检查 AllowDeviceRead 语句（允许遍历）。如果操作是对任何设备 FRN 执行 devices:Read 或 devices:List，且上下文包含 principalType = "user"，则结果为 ALLOW 。
任何其他操作/资源组合将导致 默认拒绝（DENY） （无匹配）。