憑證管理角色 - API

本指南將逐步說明如何在 F5 Distributed Cloud 中建立自訂 RBAC 角色，授予管理 HTTP Load Balancer 所使用的 SSL/TLS 憑證和憑證鏈的權限。若要使用基於 UI 的方式，請參閱簡化主控台指南。

F5 XC RBAC 的運作方式

F5 XC 使用三層權限模型：

api_group_element  (唯讀，系統定義)
       │
       ▼
   api_group       (唯讀，系統定義)
       │
       ▼
     role           (完整 CRUD — 這是您要建立的部分)

api_group_element — 定義正規表達式路徑和 HTTP 方法（例如 POST /api/config/.*/certificates）。由系統管理；您無法建立、修改或刪除這些物件。
api_group — 依功能區域組織的 api_group_element 參考集合，具有命名名稱。由系統管理；您無法建立、修改或刪除這些物件。群組使用如 ves-io-proxy-read 或 f5xc-waap-standard-admin 的命名慣例。
role — 在陣列中參考 api_group 名稱。**這是您唯一需要建立的層級。**使用自訂角色端點將特定的 api_groups 附加到角色。

HTTP Load Balancer 的憑證操作與其他代理相關資源（HTTP Load Balancer、路由、來源等）一起綁定在 ves-io-proxy-* api_groups 中。平台沒有獨立的憑證專用 api_groups — 權限是依功能區域組織，而非依個別資源類型。

範圍與限制

ves-io-proxy-read 和 ves-io-proxy-write api_groups 授予對所有代理相關資源的存取權限，不僅限於憑證。被指派此角色的使用者也可以管理 HTTP Load Balancer、來源、路由和其他代理範圍內的物件。

在 F5 XC 上無法實現僅限憑證的 RBAC。api_group 和 api_group_element 都是系統定義的唯讀物件 — API 僅公開這些物件的 GET 端點。角色只能參考現有的 api_group 名稱，而且沒有任何 api_group 專門限定於憑證範圍。

**緩解措施 — 命名空間隔離：**建立專用的命名空間來存放憑證資源，並將 example-cert-admin 角色的範圍僅指派給該命名空間。使用者保留代理層級的權限，但無法存取其他命名空間中的資源，從而限制較廣泛 api_group 範圍的影響範圍。

先決條件

具有管理員權限的 F5 XC API 令牌
已安裝 curl 和 jq

設定您的環境變數：

export F5XC_TENANT="your-tenant"
export F5XC_API_URL="https://${F5XC_TENANT}.console.ves.volterra.io"
export F5XC_API_TOKEN="your-api-token"

步驟 1：探索代理 API 群組

列出所有系統定義的 api_group 物件，並篩選代理相關的項目（其中包含憑證權限）：

curl -s \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  "${F5XC_API_URL}/api/web/namespaces/shared/api_groups" \
  | jq '[.items[] | select(.name | test("ves-io-proxy")) | .name] | sort'

預期輸出：

[
  "ves-io-proxy-app-firewall-read",
  "ves-io-proxy-app-firewall-write",
  "ves-io-proxy-monitor-read",
  "ves-io-proxy-monitor-write",
  "ves-io-proxy-read",
  "ves-io-proxy-security-read",
  "ves-io-proxy-security-write",
  "ves-io-proxy-waf-read",
  "ves-io-proxy-waf-write",
  "ves-io-proxy-write"
]

對於憑證管理，相關的群組為：

API 群組	授予權限
`ves-io-proxy-read`	對代理資源（包含憑證）的讀取權限
`ves-io-proxy-write`	對代理資源（包含憑證）的寫入權限

步驟 2：建立自訂角色

使用自訂角色建立端點。api_groups 陣列參考在步驟 1 中探索到的系統定義 api_group 名稱。

建立具有代理資源（包含憑證和憑證鏈）讀寫權限的自訂角色：

curl -s -X POST \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  -H "Content-Type: application/json" \
  "${F5XC_API_URL}/api/web/custom/namespaces/system/roles" \
  -d '{
    "metadata": {
      "name": "example-cert-admin",
      "namespace": "system"
    },
    "spec": {},
    "api_groups": [
      "ves-io-proxy-read",
      "ves-io-proxy-write"
    ]
  }'

步驟 3：驗證角色

使用自訂 GET 端點擷取角色，確認 api_groups 已附加：

curl -s \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  "${F5XC_API_URL}/api/web/custom/namespaces/system/roles/example-cert-admin" \
  | jq '{name: .object.metadata.name, api_groups: .api_groups}'

預期輸出：

{
  "name": "example-cert-admin",
  "api_groups": [
    "ves-io-proxy-read",
    "ves-io-proxy-write"
  ]
}

步驟 4：更新角色（選用）

若要從現有角色新增或移除 api_groups，請使用自訂 PUT 端點：

curl -s -X PUT \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  -H "Content-Type: application/json" \
  "${F5XC_API_URL}/api/web/custom/namespaces/system/roles/example-cert-admin" \
  -d '{
    "name": "example-cert-admin",
    "namespace": "system",
    "spec": {},
    "api_groups": [
      "ves-io-proxy-read"
    ]
  }'

此範例透過移除 ves-io-proxy-write 將角色降級為唯讀存取。

步驟 5：刪除角色（選用）

刪除使用標準角色端點：

curl -s -X DELETE \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  "${F5XC_API_URL}/api/web/namespaces/system/roles/example-cert-admin"

API 參考

角色端點（自訂 — 包含 `api_groups`）

角色始終位於 system 命名空間中。

方法	路徑	說明
POST	`/api/web/custom/namespaces/system/roles`	建立自訂角色
GET	`/api/web/custom/namespaces/system/roles`	列出自訂角色
GET	`/api/web/custom/namespaces/system/roles/{name}`	取得自訂角色
PUT	`/api/web/custom/namespaces/system/roles/{name}`	取代自訂角色

角色端點（標準）

方法	路徑	說明
DELETE	`/api/web/namespaces/system/roles/{name}`	刪除角色
GET	`/api/web/namespaces/system/roles/{name}`	取得角色
GET	`/api/web/namespaces/system/roles`	列出角色

探索端點（唯讀）

探索使用 shared 命名空間。

方法	路徑	說明
GET	`/api/web/namespaces/shared/api_groups`	列出所有 api_groups
GET	`/api/web/namespaces/shared/api_group_elements`	列出所有 api_group_elements

憑證端點（角色授予存取權限的對象）

將 {namespace} 替換為管理憑證的命名空間。

方法	路徑	說明
POST	`/api/config/namespaces/{namespace}/certificates`	建立憑證
GET	`/api/config/namespaces/{namespace}/certificates`	列出憑證
GET	`/api/config/namespaces/{namespace}/certificates/{name}`	取得憑證
PUT	`/api/config/namespaces/{namespace}/certificates/{name}`	取代憑證
DELETE	`/api/config/namespaces/{namespace}/certificates/{name}`	刪除憑證
POST	`/api/config/namespaces/{namespace}/certificate_chains`	建立憑證鏈
GET	`/api/config/namespaces/{namespace}/certificate_chains`	列出憑證鏈
GET	`/api/config/namespaces/{namespace}/certificate_chains/{name}`	取得憑證鏈
PUT	`/api/config/namespaces/{namespace}/certificate_chains/{name}`	取代憑證鏈
DELETE	`/api/config/namespaces/{namespace}/certificate_chains/{name}`	刪除憑證鏈

為什麼 `api_group` 和 `api_group_element` 是唯讀的

這些物件由 F5 XC 系統定義。平台會為每個 API 路徑預先建立 api_group_element 項目，並將它們依功能區域分組到 api_group 物件中。

您不需要建立這些物件 — 系統中的每個資源都已經有對應的物件。您的工作是探索相關的群組名稱（步驟 1），並在自訂角色中參考它們（步驟 2）。

若要查看 api_group 涵蓋哪些個別 API 路徑，請列出 api_group_elements 端點並尋找與您的資源相關的元素：

curl -s \
  -H "Authorization: APIToken ${F5XC_API_TOKEN}" \
  "${F5XC_API_URL}/api/web/namespaces/shared/api_group_elements" \
  | jq '[.items[] | select(.name | test("ves-io-schema-certificate")) | .name]'