授权模型¶

DotID 的授权服务实现了一个受 AWS IAM 启发的 基于资源的访问控制 系统。它充当 策略决策点（PDP） ：调用方描述*谁 * 想对*哪个资源 * 执行*什么操作* ，服务返回 ALLOW 或 DENY。

核心概念¶

账户¶

账户是顶层的组织容器（租户）。每个资源 FRN 都包含一个 account-id 段，以便策略可以按租户划分范围。

组¶

组将一个或多个主体（用户或服务账户客户端）聚集在一起。组是授权模型中"谁"这一维度。

每个成员作为 GroupMember 存储，包含以下信息：

principalId -- Keycloak 主体标识符（sub 声明）。
principalType -- user 或 client。

一个主体可以属于多个组。

策略集与策略¶

策略集（PolicySet） 是一个命名容器，用于将相关策略归组。

策略（Policy） 以 PostgreSQL jsonb 格式存储的 JSON document 中保存实际的授权规则。完整模式请参阅策略文档格式。

权限（绑定）¶

权限是一个三方绑定，用于回答以下问题：

"当组 G 的成员访问账户 A 中的资源时，哪些策略适用？"

答案是策略集 S 中包含的策略。

Principal  -->  GroupMember  -->  Group
                                   |
                               Permission
                                   |
                          Account (resource scope)
                                   |
                              PolicySet
                                   |
                              Policy (1..N)
                                   |
                            Statement[]

元组 (group_id, account_id, policy_set_id) 是唯一的——重复的绑定将被拒绝并返回 HTTP 409。

评估算法¶

PolicyDecisionService 实现了经典的 显式拒绝优先 评估模型。单次授权检查按以下步骤进行：

解析资源 FRN -- 验证 FRN 字符串；立即拒绝格式错误的标识符。
Resource-based policy -- if a resource policy exists for the target FRN and explicitly allows/denies the action, return early.
Root user bypass -- root users have implicit full access to their own account (like AWS root), no policy attachment needed. If the principal is a root user and the target resource belongs to the same account, return ALLOW with reason ROOT_USER_BYPASS.
Resolve identity-based policies -- resolves group memberships via account assignments, IAM managed/inline policies, and permission set policies for the principal.
第一遍 -- 显式拒绝 ：遍历所有 "Effect": "Deny" 的语句。如果任何语句匹配，则立即返回 DENY （拒绝始终优先）。
SCP evaluation -- for principals in an organization, evaluate Service Control Policies. If the action is not allowed by any SCP, return DENY.
第一遍 -- 显式拒绝 ：遍历所有 "Effect": "Deny" 的语句。如果任何语句匹配，则立即返回 DENY （拒绝始终优先）。
Delegated Admin Allow -- if no identity policy granted access, check whether the principal qualifies as a delegated administrator:
- The principal must be a root user (userType == "root").
- The principal's account must have a delegation for the action's service namespace (the prefix before the first : in the action string, e.g., "audit" from "audit:Event:Read").
- The namespace must be eligible for delegation (see below).
- The target resource must belong to an account within the same organization as the delegation.
- Requests targeting the principal's own account are skipped (root users already have full access on their own account).
- Wildcard FRN targets (account segment *) are allowed.
If all conditions pass, the check returns matchedStatement: "DelegatedAdminAllow" and proceeds to the permission boundary check.

Namespace delegation eligibility

Only operational and observability namespaces may be delegated. Governance and security-critical namespaces are permanently excluded to prevent privilege escalation:
- iam -- not delegable. A delegate could modify or remove other users' permissions, including the root user's own policies.
- org -- not delegable. Organization structure is a management-account-only concern.
- scp -- not delegable. Delegating SCP management would allow weakening security guardrails across the organization.
- sts -- not delegable. Cross-account role assumption is identity infrastructure, not an operational service.
- audit -- delegable. Read-only audit log access for org-wide compliance visibility.
- quota -- delegable. View and manage service quotas across the organization.
Future namespaces follow the same rule: if delegating the namespace could allow the delegate to alter, escalate, or remove permissions for other principals, it must not be delegable.
Permission boundary -- if a permission boundary is set for the user, verify the action is within the boundary. If not, return DENY.
Return ALLOW -- if a matching allow statement (or delegation grant) survived all checks, return ALLOW.
默认拒绝 ：如果没有语句匹配，则返回 DENY 。
审计日志 -- 每个决策（包括默认拒绝）都会持久化到 authorization_audit_log。

语句匹配¶

仅当以下 全部三项 子检查通过时，语句才算匹配：

操作匹配

精确匹配："devices:Read" 仅匹配 "devices:Read"。
全局通配符："*" 匹配任何操作。
服务前缀通配符："devices:*" 匹配以 "devices:" 开头的任何操作。

资源匹配

字面量 "*" 匹配任何资源。
否则，模式将被解析为 FRN，并使用 FrnMatcher 逐段匹配（参见 FRN 规范）。

条件匹配

条件基于请求的 context 映射施加额外约束。语句中的所有运算符都必须通过（AND 逻辑）。

支持的条件运算符¶
运算符	语义
`StringEquals`	`actual` 必须在期望值列表中（精确匹配）。
`StringNotEquals`	`actual` 不得在期望值列表中。
`StringLike`	`actual` 必须匹配至少一个 glob 模式（`*` = 任意字符）。
`Bool`	`actual.toString()` 必须在期望值列表中（例如 `"true"`）。

未知运算符将被评估为 false 并记录警告。

条件键可以携带 dotid: 前缀（查找前会被去除）。上下文键会以原始形式和从 camelCase 转换为 snake_case 的形式进行尝试。

批量评估¶

批量端点为一个主体 一次性 加载组成员关系和策略，然后针对预加载的数据评估每项检查。这比逐一发送请求高效得多。

Capabilities¶

Capabilities are account-level business qualifications stored on the Account entity in the DotID authorization service. They are distinct from — and evaluated after — the SCP/IAM policy evaluation described above.

批量评估

Roles, SCPs, and IAM policies are evaluated (steps 1–11 above).
If the result is ALLOW, the target service checks whether the account holds the required capability for the requested operation.
If the capability is absent, the service returns 403 Forbidden ("account not qualified — contact platform support").

Capabilities are not part of the policy document format and are not evaluated by the Policy Decision Point. They are checked independently by each service after authorization passes.

Known capabilities:

enroll_things — register new devices in ThingHub
approve_licenses — approve and issue licenses in TrustMint
publish_marketplace — publish products to the Bazaar marketplace
manage_ota_rollouts — create and manage OTA rollouts in OTAForge

Capabilities are granted and revoked by platform admins in SuperCrew. Accounts start with no capabilities. See Access Control Layers for the full three-layer model (Role → SCP → Capability) and how these layers interact.

缓存失效¶

对任何授权实体的每次变更（创建、更新、删除）都会递增全局 策略版本 计数器，并通过 Server-Sent Events (SSE) 广播 policy.changed 事件。

下游缓存应执行以下任一操作：

订阅 GET /api/v1/events/stream，并在收到任何事件时进行缓存失效处理；或者
定期轮询 GET /api/v1/policy-version。