Autorisation dans APISIX utilisant Casbin

Introduction

Apache APISIX peut appliquer les politiques d'autorisation Casbin au niveau de la passerelle grâce à son plugin intégré authz-casbin. Le plugin utilise Lua Casbin et prend en charge les modèles de contrôle d'accès tels que ACL, RBAC et ABAC.

Ce guide place une petite politique RBAC sur le chemin de requête APISIX. Vous vérifierez les requêtes autorisées et refusées, puis mettrez à jour une politique partagée via les métadonnées du plugin sans modifier la route.

La communauté Casbin a initialement proposé l'intégration dans APISIX Issue #4674, et APISIX PR #4710 a ajouté le plugin.

Actualisation août 2026

Ce guide a été actualisé en août 2026. Les exemples ont été validés avec Apache APISIX 3.17.0. L'auteur original de 2021 reste crédité, et Yilia Lin est ajoutée pour l'actualisation de 2026.

Frontière d'authentification

Casbin effectue l'autorisation, pas l'authentification. L'exemple utilise un en-tête de requête user comme sujet uniquement pour garder le test simple. En production, ne faites pas confiance à un en-tête d'identité fourni directement par un client. Une couche d'authentification ou un proxy fiable doit établir l'identité et supprimer ou écraser les valeurs non fiables avant que Casbin n'évalue la requête.

Prérequis et état initial

Ce guide commence avec une instance jetable Apache APISIX 3.17.0 déjà en cours d'exécution. Si vous avez besoin d'une instance locale, suivez le guide de déploiement APISIX Docker et épinglez l'image APISIX sur apache/apisix:3.17.0-debian.

L'instance doit avoir :

• le plan de données disponible sur http://127.0.0.1:9080;
• l'API Admin disponible sur http://127.0.0.1:9180;
• les plugins intégrés authz-casbin et mocking activés.

Vous avez également besoin de curl et jq. Définissez admin_key avec la clé configurée pour votre API Admin:

export admin_key='<your-admin-api-key>'

Remplacez le placeholder avant de continuer. Confirmez que l'API Admin est accessible et que le plugin est activé:

curl --fail-with-body \
  "http://127.0.0.1:9180/apisix/admin/plugins/list" \
  -H "X-API-KEY: $admin_key" | \
jq -e '(["authz-casbin", "mocking"] - .) | length == 0'

La commande doit afficher true. Ne publiez pas l'API Admin sur un réseau non fiable ni ne réutilisez les identifiants de démonstration dans un autre environnement.

Définir le modèle et la politique

Le plugin évalue trois valeurs de requête:

• sub: le sujet provenant de l'en-tête de requête configuré;
• obj: le chemin URI de la requête; et
• act: la méthode HTTP.

Créez model.conf:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = (g(r.sub, p.sub) || keyMatch(r.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)

Créez policy.csv:

p, *, /anything, GET
p, admin, *, *
g, alice, admin

Cette politique permet à n'importe quel sujet d'envoyer GET /anything. Elle attribue également à alice le rôle admin, qui peut accéder à tous les chemins avec toutes les méthodes.

Stocker la politique partagée dans les métadonnées du plugin

Chargez les fichiers sous forme de chaînes JSON et écrivez-les dans les métadonnées du plugin APISIX:

jq -n \
  --rawfile model model.conf \
  --rawfile policy policy.csv \
  '{model: $model, policy: $policy}' | \
curl --fail-with-body \
  "http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin" \
  -H "X-API-KEY: $admin_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  --data-binary @-

Les métadonnées du plugin fournissent un modèle et une politique aux routes qui activent authz-casbin sans définir leur propre modèle et politique local à la route.

Activer l'autorisation sur une route

Créez une route et indiquez au plugin de lire le sujet depuis l'en-tête user:

curl --fail-with-body \
  "http://127.0.0.1:9180/apisix/admin/routes/casbin-demo" \
  -H "X-API-KEY: $admin_key" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "uri": "/*",
    "plugins": {
      "authz-casbin": {
        "username": "user"
      },
      "mocking": {
        "_meta": {
          "priority": 1000
        },
        "response_status": 200,
        "response_example": "{\"message\":\"authorized\"}"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "127.0.0.1:1": 1
      }
    }
  }'

La route utilise le modèle et la politique des métadonnées du plugin car elle ne définit localement que le champ username. Un modèle et une politique locaux à la route, lorsqu'ils sont configurés, ont priorité sur les métadonnées du plugin.

Le plugin mocking fournit aux requêtes autorisées une réponse locale déterministe, afin que l'exemple ne dépende pas d'un upstream public. Sa priorité locale à la route est inférieure à celle de authz-casbin, ce qui fait que la décision d'autorisation s'exécute en premier. L'upstream inaccessible n'est donc pas contacté. Cette priorité et cette réponse simulée sont des fixtures de test, pas des recommandations de production.

Vérifier les décisions d'autorisation et de refus

Une requête anonyme vers le chemin public est autorisée:

curl -i http://127.0.0.1:9080/anything

Statut attendu:

HTTP/1.1 200 OK
{"message":"authorized"}

bob n'a pas le rôle admin, donc un chemin différent est refusé:

curl -i http://127.0.0.1:9080/anything/res -H 'user: bob'

Résultat attendu:

HTTP/1.1 403 Forbidden
{"message":"Access Denied"}

alice a le rôle admin, donc la même requête est autorisée:

curl -i http://127.0.0.1:9080/anything/res -H 'user: alice'

Statut attendu:

HTTP/1.1 200 OK
{"message":"authorized"}

Mettre à jour la politique partagée

Ajoutez une permission directe pour bob dans policy.csv:

p, *, /anything, GET
p, admin, *, *
p, bob, /anything/res, GET
g, alice, admin

Exécutez à nouveau la commande des métadonnées du plugin. Les routes qui référencent ces métadonnées utilisent la politique mise à jour sans modifier leur configuration de route. Répétez la requête:

curl -i http://127.0.0.1:9080/anything/res -H 'user: bob'

Le résultat attendu est maintenant:

HTTP/1.1 200 OK
{"message":"authorized"}

Choisir la portée de configuration

Utilisez les métadonnées du plugin lorsque plusieurs routes doivent partager un seul modèle et une seule politique. Utilisez un modèle et une politique locaux à la route lorsqu'une route a besoin d'une structure d'autorisation indépendante. Pour le schéma de configuration complet et l'alternative basée sur des fichiers, consultez la référence du plugin APISIX authz-casbin.

Nettoyage

Supprimez la route de test:

curl --fail-with-body \
  "http://127.0.0.1:9180/apisix/admin/routes/casbin-demo" \
  -H "X-API-KEY: $admin_key" \
  -X DELETE

Supprimez les métadonnées partagées du plugin:

curl --fail-with-body \
  "http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin" \
  -H "X-API-KEY: $admin_key" \
  -X DELETE