Ruolo Certificate Admin - API

Questa guida illustra la creazione di un ruolo RBAC personalizzato in F5 Distributed Cloud che concede i permessi per gestire certificati SSL/TLS e catene di certificati utilizzati dagli HTTP Load Balancer. Per un approccio basato sull’interfaccia utente, consultare la guida semplificata alla console.

Come Funziona l’RBAC di F5 XC

F5 XC utilizza un modello di permessi a tre livelli:

api_group_element  (sola lettura, definito dal sistema)
       │
       ▼
   api_group       (sola lettura, definito dal sistema)
       │
       ▼
     role           (CRUD completo — questo è ciò che si crea)

1. api_group_element — Definisce un percorso regex e metodi HTTP (es. POST /api/config/.*/certificates). Gestito dal sistema; non è possibile creare, modificare o eliminare questi elementi.

2. api_group — Una raccolta denominata di riferimenti ad api_group_element, organizzata per area funzionale. Gestita dal sistema; non è possibile creare, modificare o eliminare questi elementi. I gruppi utilizzano convenzioni di denominazione come ves-io-proxy-read o f5xc-waap-standard-admin.

3. role — Fa riferimento a nomi di api_group in un array. Questo è l’unico livello che si crea. Utilizzare gli endpoint dei ruoli personalizzati per associare specifici api_groups a un ruolo.

Le operazioni sui certificati per gli HTTP Load Balancer sono raggruppate negli api_groups ves-io-proxy-* insieme ad altre risorse relative al proxy (HTTP Load Balancer, route, origin, ecc.). Non esistono api_groups dedicati esclusivamente ai certificati — la piattaforma organizza i permessi per area funzionale, non per singolo tipo di risorsa.

Ambito e Limitazioni

Gli api_groups ves-io-proxy-read e ves-io-proxy-write concedono l’accesso a tutte le risorse relative al proxy, non solo ai certificati. Un utente a cui viene assegnato questo ruolo può anche gestire HTTP Load Balancer, origin, route e altri oggetti nell’ambito del proxy.

L’RBAC limitato ai soli certificati non è possibile su F5 XC. Sia api_group che api_group_element sono oggetti di sola lettura definiti dal sistema — l’API espone solo endpoint GET per questi. I ruoli possono fare riferimento solo a nomi di api_group esistenti, e non esiste un api_group con ambito esclusivo per i certificati.

Mitigazione — isolamento del namespace: Creare un namespace dedicato per le risorse dei certificati e assegnare il ruolo example-cert-admin con ambito limitato solo a quel namespace. L’utente mantiene i permessi a livello proxy ma non può accedere alle risorse in altri namespace, limitando il raggio d’impatto dell’ambito più ampio dell’api_group.

Prerequisiti

• Un token API F5 XC con privilegi di amministratore
• curl e jq installati

Impostare le variabili d’ambiente:

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

Passaggio 1: Individuare gli API Group del Proxy

Elencare tutti gli oggetti api_group definiti dal sistema e filtrare le voci relative al proxy (che includono i permessi per i certificati):

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'

Output atteso:

[
  "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"
]

Per la gestione dei certificati, i gruppi rilevanti sono:

API Group	Permessi Concessi
ves-io-proxy-read	Accesso in lettura alle risorse proxy inclusi i certificati
ves-io-proxy-write	Accesso in scrittura alle risorse proxy inclusi i certificati

Nota

Questi gruppi coprono tutte le risorse relative al proxy (HTTP Load Balancer, origin, route, certificati, catene di certificati, ecc.), non solo i certificati. F5 XC organizza i permessi per area funzionale. Se è necessario verificare quali percorsi API specifici un gruppo concede, consultare l’endpoint api_group_elements descritto nella sezione Riferimento API.

Passaggio 2: Creare il Ruolo Personalizzato

Utilizzare l’endpoint di creazione del ruolo personalizzato. L’array api_groups fa riferimento ai nomi degli api_group definiti dal sistema individuati nel Passaggio 1.

Creare il ruolo personalizzato con accesso in lettura e scrittura alle risorse proxy (inclusi certificati e catene di certificati):

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"
    ]
  }'

Passaggio 3: Verificare il Ruolo

Recuperare il ruolo utilizzando l’endpoint GET personalizzato per confermare che gli api_groups sono associati:

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}'

Output atteso:

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

Passaggio 4: Aggiornare il Ruolo (Opzionale)

Per aggiungere o rimuovere api_groups da un ruolo esistente, utilizzare l’endpoint PUT personalizzato:

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"
    ]
  }'

Questo esempio declassa il ruolo ad accesso in sola lettura rimuovendo ves-io-proxy-write.

Passaggio 5: Eliminare il Ruolo (Opzionale)

L’eliminazione utilizza l’endpoint standard dei ruoli:

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

Riferimento API

Endpoint dei Ruoli (Personalizzati — includono api_groups)

I ruoli sono sempre nel namespace system.

Metodo	Percorso	Descrizione
POST	/api/web/custom/namespaces/system/roles	Creare un ruolo personalizzato
GET	/api/web/custom/namespaces/system/roles	Elencare i ruoli personalizzati
GET	/api/web/custom/namespaces/system/roles/{name}	Ottenere un ruolo personalizzato
PUT	/api/web/custom/namespaces/system/roles/{name}	Sostituire un ruolo personalizzato

Endpoint dei Ruoli (Standard)

Metodo	Percorso	Descrizione
DELETE	/api/web/namespaces/system/roles/{name}	Eliminare un ruolo
GET	/api/web/namespaces/system/roles/{name}	Ottenere un ruolo
GET	/api/web/namespaces/system/roles	Elencare i ruoli

Endpoint di Discovery (Sola Lettura)

Il discovery utilizza il namespace shared.

Metodo	Percorso	Descrizione
GET	/api/web/namespaces/shared/api_groups	Elencare tutti gli api_groups
GET	/api/web/namespaces/shared/api_group_elements	Elencare tutti gli api_group_elements

Endpoint dei Certificati (A Cosa il Ruolo Concede l’Accesso)

Sostituire {namespace} con il namespace in cui vengono gestiti i certificati.

Metodo	Percorso	Descrizione
POST	/api/config/namespaces/{namespace}/certificates	Creare un certificato
GET	/api/config/namespaces/{namespace}/certificates	Elencare i certificati
GET	/api/config/namespaces/{namespace}/certificates/{name}	Ottenere un certificato
PUT	/api/config/namespaces/{namespace}/certificates/{name}	Sostituire un certificato
DELETE	/api/config/namespaces/{namespace}/certificates/{name}	Eliminare un certificato
POST	/api/config/namespaces/{namespace}/certificate_chains	Creare una catena di certificati
GET	/api/config/namespaces/{namespace}/certificate_chains	Elencare le catene di certificati
GET	/api/config/namespaces/{namespace}/certificate_chains/{name}	Ottenere una catena di certificati
PUT	/api/config/namespaces/{namespace}/certificate_chains/{name}	Sostituire una catena di certificati
DELETE	/api/config/namespaces/{namespace}/certificate_chains/{name}	Eliminare una catena di certificati

Perché api_group e api_group_element Sono in Sola Lettura

Questi oggetti sono definiti dal sistema da F5 XC. La piattaforma pre-crea le voci api_group_element per ogni percorso API e le raggruppa in oggetti api_group organizzati per area funzionale.

Non è necessario creare questi elementi — esistono già per ogni risorsa nel sistema. Il compito dell’utente è individuare i nomi dei gruppi rilevanti (Passaggio 1) e farvi riferimento nel proprio ruolo personalizzato (Passaggio 2).

Per vedere quali percorsi API individuali copre un api_group, elencare l’endpoint api_group_elements e cercare gli elementi relativi alla propria risorsa:

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]'