指派角色與權限

何時用這份文件 你要給某人權限做某件事（建 Issue / 跑 Rollout / 查 audit log / 管 IdP）。

前置條件

• 你的角色擁有 bb.workspaces.setIamPolicy（workspace 級）或 bb.projects.setIamPolicy（project 級）
• 對方已建好帳號（建立帳號）
• 已讀過 IAM Binding（特別是「最小權限」原則與 13 個內建 role）

決策樹

這個人需要什麼權限？
       │
       ▼
┌──────────────────────────────────────────┐
│ 範圍是「跨所有 project」還是「單一 project」？ │
└──────────────────────────────────────────┘
       │
       ├─ 跨所有 → workspace-level binding
       │           └─ workspaceAdmin / workspaceDBA /
       │              workspaceMember / sqlEditorUser /
       │              secondaryBusinessOps / securityOfficer /
       │              readOnlyAuditor
       │
       └─ 單一 → project-level binding
                  └─ projectOwner / projectDeveloper /
                     projectReleaser / projectQuerier /
                     projectExporter / projectViewer

Workspace 級 Binding

給「跨所有 project都生效」的權限。

Settings → Members & Roles：

動作	操作
新增 binding	選 user / group → 選 role → Save
刪除 binding	從清單刪掉那一列
改 binding	先刪舊的再加新的（GET-modify-SET pattern）

13 個內建 role 速選

我想給什麼	用哪個 role
全公司平台管理員	workspaceAdmin
跨 project DBA	workspaceDBA
一般使用者（讀大多數內容）	workspaceMember
純 SQL Editor 查詢	sqlEditorUser
二線業務運維（讀 + 審批，但不能改 SQL）	secondaryBusinessOps
資安 / 合規（管 IAM / policy，不參與業務審批）	securityOfficer
唯讀稽核（含 audit log）	readOnlyAuditor

⚠️ workspaceAdmin 是最強權限，含改 IdP / IAM 的能力。給最少的人。

Project 級 Binding

給「單一 project內生效」的權限。

Projects → <p> → Members：

6 個 project role

Role	一句話
projectOwner	該 project 全權；管成員、改 setting、release
projectDeveloper	提交 Plan、評論、看 issue
projectReleaser	觸發 Rollout、執行 issue
projectQuerier	唯讀查詢（含 SQL Editor）
projectExporter	匯出資料
projectViewer	該 project 唯讀（不含 SQL Editor）

常見組合

場景	binding
後端工程師（單一 project）	projectDeveloper
平台工程師（跨 project）	workspace 給 workspaceMember + 必要 project 給 projectOwner
DBA 跨 project	workspace 給 workspaceDBA
契約工（單一 project，唯讀）	projectViewer 或 projectQuerier
業務分析師（要查資料）	projectQuerier

用 Group 而不是個人

強烈建議：對團隊權限透過 group binding，不要個別綁人。

推薦：
  Group "backend-team"  ──> projectDeveloper at project "play"
  Members of group:
    - alice
    - bob
    - charlie

不推薦：
  alice    ──> projectDeveloper at project "play"
  bob      ──> projectDeveloper at project "play"
  charlie  ──> projectDeveloper at project "play"

理由：

• 新人加入 → 加進 group 即可，不必到每個 project 加 binding
• 離職 → 從 group 移除即可，所有 project 權限同時清掉
• 一致性更好稽核

API 操作

Binding 是整批覆寫（不是 incremental）。先 GET、改、再 SET。

# 1. GET 當前 policy
curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/workspaces/-:getIamPolicy" > policy.json

# 2. 編輯 policy.json（加新 binding 或改 role）
jq '.bindings += [{
  "role": "roles/readOnlyAuditor",
  "members": ["user:login_id=external-auditor-2026"]
}]' policy.json > policy-new.json

# 3. SET 新 policy
curl -X POST -H "Authorization: Bearer $TOKEN" \
  --data @<(jq '{policy: .}' policy-new.json) \
  "$ARGUS/v1/workspaces/-:setIamPolicy"

⚠️ 兩個人同時改 = 後寫覆蓋前寫。如果 race 風險高，policy 帶 etag，server 會檢查並回 409。

移除權限

個別撤銷

Settings → Members → <user> → 點對應 role 旁的 Revoke。

Deactivate user（離職）

Settings → Members → <user> → Deactivate：

• 該 user 所有 session 失效
• 該 user 所有 binding 仍存在（保留稽核軌跡上的 actor 指向），但永遠無法登入
• audit log 上的 actor = <user> 仍可顯示

不要 delete user，會破壞 audit log 指向。

撤銷整個 role（移除一群人）

# 取出 binding 並濾掉指定 role
jq '.bindings |= map(select(.role != "roles/projectReleaser"))' policy.json > new.json
# 再 SET

暫時權限（過期 binding）

expires_at 欄位讓 binding 自動過期。適合：

• 契約工 / 臨時協力
• 事故支援臨時授權
• 外部稽核期間

jq '.bindings += [{
  "role": "roles/projectDeveloper",
  "members": ["user:login_id=contractor-001"],
  "condition": {
    "expression": "request.time < timestamp(\"2026-08-31T23:59:59Z\")"
  }
}]' policy.json > new.json

過期後 binding 自動失效（user 無此 role）。

審計

所有 binding 異動寫 audit log：

Action
bb.workspaces.setIamPolicy
bb.projects.setIamPolicy
bb.role.assign / bb.role.revoke（細粒度 derived event）

bb.workspaces.setIamPolicy 的 payload 含 before/after 差異，方便事後 diff。

不要做的事

反模式	為什麼
「全部給 workspaceAdmin 比較好做事」	違反最小權限；任何人可改 IdP / IAM
對每個人個別綁 binding	維護成本高、容易遺漏
拒絕用 group	同上
離職 user delete 帳號	破壞 audit log actor 指向
給外部 user mutation 權限	違反零信任；外部一律給 readOnlyAuditor / projectViewer
過期 binding 不清	一年後一堆殘留 binding，沒人記得當初為何給

相關

• 概念：IAM Binding
• 建立帳號：建立帳號（無 IdP 流程）
• 認證：認證模式
• 稽核：Audit Log