ACL Consul en profondeur — bootstrap, policies, tokens et rotation 2026

📍 Article principal du cluster : HashiCorp Consul Associate (003) — guide pratique de la certification 2026

Ce tutoriel fait partie du cluster certification Consul Associate. Pour la vue d’ensemble, lisez d’abord le pilier.

Introduction

Les ACL constituent le domaine 7 du syllabus Consul Associate et représentent statistiquement environ 15-20 % des questions d’examen — la portion la plus dense du programme après le service mesh. Beaucoup de candidats échouent précisément ici parce qu’ils confondent les concepts de policy, role et token, ou parce qu’ils n’ont jamais bootstrappé un système ACL en pratique. Ce tutoriel corrige ces lacunes : vous allez activer le système ACL avec une politique default-deny, bootstrapper le master token, écrire trois policies à privilèges minimaux pour des cas d’usage différents (lecture du KV, écriture sur un service spécifique, opérateur d’observabilité), créer des tokens auto-renouvelables pour les agents clients, et terminer par une rotation complète du master token. Tout cela sur le cluster Consul issu des trois tutoriels précédents.

Prérequis

• Cluster Consul fonctionnel avec service mesh activé (issu des tutoriels précédents)
• Notions de RBAC (rôles, politiques, droits)
• 40 minutes

Étape 1 — Comprendre le modèle ACL Consul avant d’activer

Le système ACL de Consul s’articule autour de quatre objets distincts qu’il faut absolument savoir nommer et différencier pour l’examen. Le token est l’unité d’authentification : c’est un secret UUID que les clients (humains, applications, agents) présentent à Consul pour s’identifier. Une policy est un ensemble de règles écrites en HCL ou JSON qui définit ce qu’un porteur peut faire — par exemple « lire les services dont le nom commence par api- », « écrire sur la clé KV config/app1 », « gérer tous les ACL ». Un role est un regroupement nommé de policies et de service identities, créé pour faciliter la gestion à grande échelle. Une service identity est une policy auto-générée qui donne à un service le droit de s’enregistrer et de gérer ses propres health checks.

Quand vous attachez un token à un agent ou à une application, Consul calcule l’union des policies et roles assignés au token, et applique les règles au prorata. Le mode default-deny signifie qu’en l’absence de règle explicite allow, l’opération est refusée. C’est exactement ce qu’on configure en production.

Étape 2 — Activer le système ACL en mode default-deny

L’activation se fait en éditant la configuration de chaque serveur Consul puis en redémarrant. Important : on active d’abord en mode default-allow pour ne pas casser le cluster, on bootstrap le master token, on crée les tokens applicatifs et agent, puis on bascule en default-deny une fois tout en place.

for srv in consul-srv-1 consul-srv-2 consul-srv-3; do
  incus exec $srv -- bash -c "cat >> /etc/consul.d/consul.hcl <<EOF

acl {
  enabled = true
  default_policy = \"allow\"
  enable_token_persistence = true
  tokens {
    initial_management = \"\"
  }
}
EOF"
  incus exec $srv -- systemctl restart consul
done

sleep 10
incus exec consul-srv-1 -- consul members

Après le redémarrage, le système ACL est activé mais en mode permissif (`default_policy = « allow »`). Le cluster doit toujours fonctionner normalement à ce stade — vérifiez avec `consul members`.

Étape 3 — Bootstrapper le master token

Le master token (officiellement « initial management token ») est le token racine qui permet de tout faire. On le génère une seule fois et on le stocke en lieu sûr — sans lui, vous ne pouvez ni créer d’autres tokens, ni les révoquer.

incus exec consul-srv-1 -- consul acl bootstrap

# La sortie ressemble à :
# AccessorID:       72ed8c1c-...
# SecretID:         d7ad8c2e-...
# Description:      Bootstrap Token
# Local:            false
# Create Time:      ...

# Récupérer le SecretID dans une variable pour la suite
MGMT_TOKEN=$(incus exec consul-srv-1 -- consul acl bootstrap 2>&1 | grep SecretID | awk '{print $2}')
# Si bootstrap a déjà été fait, récupérer le token précédemment sauvegardé manuellement

Le SecretID retourné est votre master token. Notez-le immédiatement dans un gestionnaire de mots de passe — vous ne pourrez plus le récupérer si vous le perdez. La seule option de récupération est un reset du système ACL (`consul acl bootstrap-reset`) qui invalide tous les tokens existants et exige un redémarrage du cluster.

Étape 4 — Écrire trois policies à privilèges minimaux

On crée maintenant trois policies pour trois cas d’usage typiques. Le format HCL des policies est documenté précisément dans le syllabus 7b et ses subtilités tombent régulièrement à l’examen.

export CONSUL_HTTP_TOKEN=$MGMT_TOKEN

# Policy 1 — lecture seule du catalogue + KV
cat > /tmp/policy-readonly.hcl <<'EOF'
service_prefix "" {
  policy = "read"
}
key_prefix "" {
  policy = "read"
}
node_prefix "" {
  policy = "read"
}
EOF
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl policy create -name "readonly" -rules @/tmp/policy-readonly.hcl

# Policy 2 — écriture exclusivement sur api-orders et son KV
cat > /tmp/policy-api-orders-write.hcl <<'EOF'
service "api-orders" {
  policy = "write"
}
key_prefix "config/api-orders/" {
  policy = "write"
}
EOF
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl policy create -name "api-orders-writer" -rules @/tmp/policy-api-orders-write.hcl

# Policy 3 — opérateur observabilité (lecture catalog + agent metrics)
cat > /tmp/policy-observer.hcl <<'EOF'
service_prefix "" {
  policy = "read"
}
node_prefix "" {
  policy = "read"
}
agent_prefix "" {
  policy = "read"
}
operator = "read"
EOF
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl policy create -name "observer" -rules @/tmp/policy-observer.hcl

# Lister les policies créées
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl policy list

Notez la différence entre `service` et `service_prefix` : le premier matche un nom exact, le second matche tous les services dont le nom commence par la chaîne donnée. Cette nuance tombe systématiquement en domaine 7b — les policies trop permissives utilisent souvent un `service_prefix «  »` (qui matche tout) là où un `service « X »` aurait été plus rigoureux.

Étape 5 — Créer des tokens à partir des policies

Les tokens sont les objets qu’on distribue aux clients. Chaque token reçoit une description, une ou plusieurs policies, et optionnellement une expiration et un namespace.

# Token avec la policy readonly
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl token create \
  -description "Token observabilité Grafana" \
  -policy-name "observer"

# Token écriture sur api-orders avec expiration 24h
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl token create \
  -description "Token CI/CD api-orders" \
  -policy-name "api-orders-writer" \
  -expires-ttl "24h"

# Token agent dédié pour consul-cli-1
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl token create \
  -description "Agent token consul-cli-1" \
  -node-identity "consul-cli-1:dc1"

Le `node-identity` est une raccourci puissant : Consul génère automatiquement une policy qui autorise le nœud nommé à se rejoindre au cluster, à enregistrer ses services, et à mettre à jour ses health checks — exactement ce dont un agent client a besoin et rien de plus. Notez précieusement les SecretID retournés.

Étape 6 — Configurer les agents clients avec leur token

Les agents clients doivent maintenant présenter un token valide pour parler au cluster. On configure le token agent dans le bloc `acl.tokens.agent` de la configuration locale.

CLIENT_TOKEN="..."  # Le SecretID du token node-identity créé à l'étape 5

incus exec consul-cli-1 -- bash -c "cat >> /etc/consul.d/consul.hcl <<EOF

acl {
  enabled = true
  default_policy = \"deny\"
  tokens {
    agent = \"$CLIENT_TOKEN\"
    default = \"$CLIENT_TOKEN\"
  }
}
EOF"

incus exec consul-cli-1 -- systemctl restart consul
sleep 5
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul members

Le token `default` est utilisé pour les opérations effectuées par l’agent en l’absence de token explicite (par exemple les health checks). Le token `agent` est spécifiquement utilisé pour les opérations système de l’agent. Si l’agent ne peut pas se rejoindre au cluster après le redémarrage, vérifiez les permissions du token via `consul acl token read -id ` — souvent le node-identity manquant ou typo.

Étape 7 — Basculer en mode default-deny

C’est le moment critique. On change `default_policy = « allow »` en `default_policy = « deny »` sur les serveurs et on redémarre. À partir de là, toute opération sans token valide est refusée.

for srv in consul-srv-1 consul-srv-2 consul-srv-3; do
  incus exec $srv -- sed -i 's/default_policy = "allow"/default_policy = "deny"/' /etc/consul.d/consul.hcl
  incus exec $srv -- systemctl restart consul
done

sleep 10

# Test 1 : sans token, on est refusé
incus exec consul-srv-1 -- consul members
# Output attendu : "Unexpected response code: 403 (Permission denied: anonymous token lacks permission)"

# Test 2 : avec le master token, ça marche
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul members

Le premier test doit échouer avec « Permission denied » et le second réussir. Vous êtes désormais en mode zero-trust : aucune opération n’est possible sans token explicite et autorisé.

Étape 8 — Rotation du master token

La rotation est un exercice critique du domaine 10. On crée un nouveau master token, on bascule, on révoque l’ancien.

# Créer un nouveau token avec policy global-management
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul acl token create \
  -description "New management token 2026-04-29" \
  -policy-name "global-management"

NEW_MGMT_TOKEN="..."  # SecretID du nouveau token

# Vérifier le nouveau token fonctionne
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$NEW_MGMT_TOKEN consul acl token list

# Révoquer l'ancien token (utiliser son AccessorID)
OLD_ACCESSOR="..."  # AccessorID de l'ancien master token
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$NEW_MGMT_TOKEN consul acl token delete -id $OLD_ACCESSOR

# Vérifier que l'ancien ne fonctionne plus
incus exec consul-srv-1 -- env CONSUL_HTTP_TOKEN=$MGMT_TOKEN consul members
# Doit retourner "Permission denied"

Cette procédure est exactement ce qui est testé en domaine 10b. Notez l’ordre crucial : créer le nouveau, le valider, puis seulement révoquer l’ancien. L’inverse vous laisse sans accès et impose un `consul acl bootstrap-reset` douloureux.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Pour les équipes plateforme Consul opérant à Dakar ou Abidjan, l’intégration des ACL avec un système d’identité d’entreprise comme Keycloak est un pattern de plus en plus courant. Consul supporte les auth methods JWT et OIDC, ce qui permet aux développeurs de récupérer un token Consul à partir de leur identité Keycloak via un endpoint OAuth — pas besoin de gérer manuellement les tokens. Cette approche est documentée dans le syllabus 7c et présente l’avantage de centraliser la révocation : on désactive un compte Keycloak et tous les tokens dérivés deviennent invalides.

Côté pratique, gardez le master token dans un coffre-fort matériel (YubiKey, Token2) ou dans Vault si vous opérez Vault en parallèle. Les tokens applicatifs courts (TTL 12-24h) renouvelés via auth method JWT sont la norme moderne — bien supérieurs aux tokens longue durée stockés dans des fichiers de configuration.

Tutoriels frères

• Installer un cluster Consul multi-nœuds
• Service mesh Consul Connect — intentions L4/L7 et mTLS

Pour aller plus loin

• 🔝 Retour au pilier : HashiCorp Consul Associate (003) — guide pratique
• Documentation officielle ACL : developer.hashicorp.com/consul/docs/security/acl
• Auth methods JWT/OIDC : developer.hashicorp.com/consul/docs/security/acl/auth-methods
• Suggestion : avec le pilier, vous avez désormais la base complète — passez aux sample questions officielles

FAQ

Combien de tokens dois-je créer en production ?
Au minimum un token par agent (clients et serveurs), un par service applicatif, un par opérateur humain, et un master token de secours stocké en coffre-fort. Pour 30 services et 5 opérateurs, comptez 70 à 80 tokens actifs en simultané — ce qui justifie une approche auth method JWT plutôt qu’une gestion manuelle.

Une intention peut-elle s’appliquer sans token ACL ?
Oui, les intentions sont indépendantes des tokens ACL. Les intentions s’appliquent au mTLS du mesh (basées sur l’identité SPIFFE), tandis que les ACL s’appliquent à l’API Consul (catalogue, KV, opérations). Les deux systèmes coexistent et se complètent.

Que se passe-t-il si on perd le master token ?
On exécute `consul acl bootstrap-reset` qui invalide tous les tokens et permet de bootstrapper à nouveau. C’est une opération qui demande accès au filesystem du leader Raft et qui interrompt brièvement le service. À éviter en heures ouvrables — préférer la rotation préventive.

Mots-clés secondaires : consul acl tutoriel, master token consul, policy hcl consul, default deny consul, rotation token, auth method jwt, service identity consul, node identity