Rôle d'administration des certificats - API

Ce guide vous accompagne dans la création d’un rôle RBAC personnalisé dans F5 Distributed Cloud qui accorde les permissions de gestion des certificats SSL/TLS et des chaînes de certificats utilisés par les HTTP Load Balancers. Pour une approche basée sur l’interface utilisateur, consultez le guide simplifié de la console.

Fonctionnement du RBAC F5 XC

F5 XC utilise un modèle de permissions à trois niveaux :

api_group_element  (lecture seule, défini par le système)
       │
       ▼
   api_group       (lecture seule, défini par le système)
       │
       ▼
     role           (CRUD complet — c'est ce que vous créez)

1. api_group_element — Définit un chemin regex et des méthodes HTTP (par ex., POST /api/config/.*/certificates). Géré par le système ; vous ne pouvez pas créer, modifier ou supprimer ces éléments.

2. api_group — Une collection nommée de références api_group_element, organisée par domaine fonctionnel. Géré par le système ; vous ne pouvez pas créer, modifier ou supprimer ces objets. Les groupes utilisent des conventions de nommage comme ves-io-proxy-read ou f5xc-waap-standard-admin.

3. role — Référence les noms d’api_group dans un tableau. C’est le seul niveau que vous créez. Utilisez les endpoints de rôle personnalisé pour attacher des api_groups spécifiques à un rôle.

Les opérations sur les certificats pour les HTTP Load Balancers sont regroupées dans les api_groups ves-io-proxy-* aux côtés d’autres ressources liées au proxy (HTTP Load Balancers, routes, origines, etc.). Il n’existe pas d’api_groups autonomes dédiés uniquement aux certificats — la plateforme organise les permissions par domaine fonctionnel, et non par type de ressource individuel.

Portée et limitations

Les api_groups ves-io-proxy-read et ves-io-proxy-write accordent l’accès à toutes les ressources liées au proxy, pas seulement aux certificats. Un utilisateur affecté à ce rôle peut également gérer les HTTP Load Balancers, les origines, les routes et d’autres objets dans le périmètre du proxy.

Le RBAC limité aux seuls certificats n’est pas possible sur F5 XC. Les objets api_group et api_group_element sont tous deux définis par le système et en lecture seule — l’API n’expose que des endpoints GET pour ceux-ci. Les rôles ne peuvent référencer que des noms d’api_group existants, et il n’existe pas d’api_group portant exclusivement sur les certificats.

Atténuation — isolation par namespace : Créez un namespace dédié pour les ressources de certificats et assignez le rôle example-cert-admin limité à ce namespace uniquement. L’utilisateur conserve les permissions au niveau proxy mais ne peut pas accéder aux ressources dans d’autres namespaces, limitant ainsi le rayon d’impact de la portée plus large de l’api_group.

Prérequis

• Un jeton API F5 XC avec des privilèges d’administrateur
• curl et jq installés

Définissez vos variables d’environnement :

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

Étape 1 : Découvrir les groupes API proxy

Listez tous les objets api_group définis par le système et filtrez les entrées liées au proxy (qui incluent les permissions sur les certificats) :

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'

Sortie attendue :

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

Pour la gestion des certificats, les groupes pertinents sont :

Groupe API	Accorde
ves-io-proxy-read	Accès en lecture aux ressources proxy incluant les certificats
ves-io-proxy-write	Accès en écriture aux ressources proxy incluant les certificats

Note

Ces groupes couvrent toutes les ressources liées au proxy (HTTP Load Balancers, origines, routes, certificats, chaînes de certificats, etc.), pas seulement les certificats. F5 XC organise les permissions par domaine fonctionnel. Si vous devez vérifier quels chemins API spécifiques un groupe accorde, consultez l’endpoint api_group_elements décrit dans la section Référence API.

Étape 2 : Créer le rôle personnalisé

Utilisez l’endpoint de création de rôle personnalisé. Le tableau api_groups référence les noms d’api_group définis par le système découverts à l’étape 1.

Créez le rôle personnalisé avec un accès en lecture et écriture aux ressources proxy (incluant les certificats et les chaînes de certificats) :

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

Étape 3 : Vérifier le rôle

Récupérez le rôle en utilisant l’endpoint GET personnalisé pour confirmer que les api_groups sont attachés :

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

Sortie attendue :

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

Étape 4 : Mettre à jour le rôle (Optionnel)

Pour ajouter ou supprimer des api_groups d’un rôle existant, utilisez l’endpoint PUT personnalisé :

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

Cet exemple rétrograde le rôle à un accès en lecture seule en supprimant ves-io-proxy-write.

Étape 5 : Supprimer le rôle (Optionnel)

La suppression utilise l’endpoint de rôle standard :

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

Référence API

Endpoints de rôle (Personnalisés — incluent les api_groups)

Les rôles sont toujours dans le namespace system.

Méthode	Chemin	Description
POST	/api/web/custom/namespaces/system/roles	Créer un rôle personnalisé
GET	/api/web/custom/namespaces/system/roles	Lister les rôles personnalisés
GET	/api/web/custom/namespaces/system/roles/{name}	Obtenir un rôle personnalisé
PUT	/api/web/custom/namespaces/system/roles/{name}	Remplacer un rôle personnalisé

Endpoints de rôle (Standard)

Méthode	Chemin	Description
DELETE	/api/web/namespaces/system/roles/{name}	Supprimer un rôle
GET	/api/web/namespaces/system/roles/{name}	Obtenir un rôle
GET	/api/web/namespaces/system/roles	Lister les rôles

Endpoints de découverte (Lecture seule)

La découverte utilise le namespace shared.

Méthode	Chemin	Description
GET	/api/web/namespaces/shared/api_groups	Lister tous les api_groups
GET	/api/web/namespaces/shared/api_group_elements	Lister tous les api_group_elements

Endpoints de certificats (Ce à quoi le rôle accorde l’accès)

Remplacez {namespace} par le namespace où vos certificats sont gérés.

Méthode	Chemin	Description
POST	/api/config/namespaces/{namespace}/certificates	Créer un certificat
GET	/api/config/namespaces/{namespace}/certificates	Lister les certificats
GET	/api/config/namespaces/{namespace}/certificates/{name}	Obtenir un certificat
PUT	/api/config/namespaces/{namespace}/certificates/{name}	Remplacer un certificat
DELETE	/api/config/namespaces/{namespace}/certificates/{name}	Supprimer un certificat
POST	/api/config/namespaces/{namespace}/certificate_chains	Créer une chaîne de certificats
GET	/api/config/namespaces/{namespace}/certificate_chains	Lister les chaînes de certificats
GET	/api/config/namespaces/{namespace}/certificate_chains/{name}	Obtenir une chaîne de certificats
PUT	/api/config/namespaces/{namespace}/certificate_chains/{name}	Remplacer une chaîne de certificats
DELETE	/api/config/namespaces/{namespace}/certificate_chains/{name}	Supprimer une chaîne de certificats

Pourquoi api_group et api_group_element sont en lecture seule

Ces objets sont définis par le système par F5 XC. La plateforme pré-crée des entrées api_group_element pour chaque chemin API et les regroupe dans des objets api_group organisés par domaine fonctionnel.

Vous n’avez pas besoin de les créer — ils existent déjà pour chaque ressource du système. Votre tâche est de découvrir les noms de groupes pertinents (Étape 1) et de les référencer dans votre rôle personnalisé (Étape 2).

Pour voir quels chemins API individuels un api_group couvre, listez l’endpoint api_group_elements et recherchez les éléments liés à votre ressource :

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