Aller au contenu principal

Autorisation pour les agents IA et les outils MCP

Un agent IA décide à l'exécution quels outils appeler et avec quels arguments. Le modèle peut se tromper, et il peut être manipulé par le texte qu'il lit dans un ticket, une page web ou un document. L'autorisation doit se situer en dehors du modèle, au point où un appel d'outil est exécuté, et répondre à deux questions :

  1. Cet agent peut-il appeler cet outil avec ces arguments ? Un assistant support peut lire des tickets et émettre de petits remboursements, mais ne devrait jamais exécuter de commandes shell.
  2. L'utilisateur pour qui il agit peut-il faire cela ? Un agent agissant pour quelqu'un ne doit pas obtenir plus d'accès que cette personne n'en a.

Casbin gère les deux avec un seul Model et une seule Policy, de la même manière qu'il gère les utilisateurs. Cette page présente d'abord les règles, puis les intègre dans une boucle simple d'appel d'outils et dans un serveur MCP. Le code est en Python. Le Model et la Policy fonctionnent également dans les autres implémentations de Casbin ; en Go, passez les arguments sous forme de struct et utilisez ses noms de champs exportés dans les conditions, comme r.args.Amount.

1. Installation​

pip install pycasbin

2. Écrire le Model​

Enregistrez ceci sous model.conf :

[request_definition]
r = sub, tool, args

[policy_definition]
p = sub, tool, cond, eft

[role_definition]
g = _, _

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

[matchers]
m = g(r.sub, p.sub) && globMatch(r.tool, p.tool) && (p.cond == '' || eval(p.cond))
  • r = sub, tool, args : l'appelant (un agent ou un utilisateur), le nom de l'outil, et les arguments de l'outil sous forme d'objet.
  • p = sub, tool, cond, eft : chaque règle nomme un rôle, un motif d'outil, une condition optionnelle sur les arguments, et si elle autorise ou refuse.
  • g = _, _ : les agents et les utilisateurs ont des rôles, et les rôles peuvent hériter d'autres rôles.
  • globMatch fait correspondre les noms d'outils avec des caractères génériques tels que tickets.* ou *.delete.
  • L'effet de la policy autorise un appel si une règle l'autorise et qu'aucune règle ne le refuse, donc une règle de refus gagne toujours.

3. Écrire la Policy​

Enregistrez ceci sous policy.csv :

p, support-agent, tickets.*, , allow
p, support-agent, orders.read, , allow
p, support-agent, orders.refund, r.args.amount <= 100, allow
p, any-agent, shell.*, , deny
p, any-agent, *.delete, , deny

p, support-staff, tickets.*, , allow
p, support-staff, orders.*, , allow

g, support-agent, any-agent
g, triage-agent, any-agent
p, triage-agent, tickets.read, , allow
p, triage-agent, tickets.label, , allow

g, alice, support-staff

En la lisant depuis le haut :

  • support-agent peut utiliser tous les outils de ticket, lire les commandes et effectuer des remboursements d'au plus 100 par appel. La condition r.args.amount <= 100 est évaluée sur les arguments produits par le modèle.
  • Tout rôle qui hérite de any-agent se voit refuser les outils shell et tout outil se terminant par .delete, quel que soit le reste des permissions accordées. Placez ici les garde-fous qui s'appliquent à tous les agents.
  • support-staff est un rôle humain ; alice le possède.
  • triage-agent est un second agent plus restreint qui ne peut que lire et étiqueter les tickets.
astuce

Écrivez les littéraux de chaîne dans les conditions avec des guillemets simples, comme dans r.args.region == 'eu'. Si une condition nécessite une virgule, enveloppez le champ entier entre guillemets doubles.

4. Vérifier chaque appel d'outil​

authorize_tool_call effectue deux vérifications. Les permissions propres à l'agent limitent ce que l'agent peut faire en général, et les permissions de l'utilisateur limitent ce qu'il peut faire pour cet utilisateur. Seuls les appels réussissant les deux vérifications sont exécutés.

tools.py
from types import SimpleNamespace

import casbin

enforcer = casbin.Enforcer("model.conf", "policy.csv")


class ToolDenied(Exception):
pass


def authorize_tool_call(agent: str, user: str, tool: str, args: dict) -> None:
"""Allow the call only if both the agent and the user it acts for may make it."""
request_args = SimpleNamespace(**args)
if not enforcer.enforce(agent, tool, request_args):
raise ToolDenied(f"{agent} may not call {tool} with {args}")
if not enforcer.enforce(user, tool, request_args):
raise ToolDenied(f"{user} may not call {tool}, so an agent acting for them may not either")


# The tools your agent can see. In a real application they call your services.
TOOLS = {
"tickets.read": lambda ticket_id: {"id": ticket_id, "subject": "Refund request", "order_id": "A-1001"},
"orders.read": lambda order_id: {"id": order_id, "total": 240},
"orders.refund": lambda order_id, amount: {"order_id": order_id, "refunded": amount},
"shell.exec": lambda command: {"output": "..."},
}


def call_tool(agent: str, user: str, tool: str, args: dict) -> dict:
"""Run a tool call proposed by the model, or return the denial as the tool result."""
try:
authorize_tool_call(agent, user, tool, args)
except ToolDenied as e:
# Returning the reason lets the model explain it or try something else.
return {"error": "permission_denied", "reason": str(e)}
return TOOLS[tool](**args)


if __name__ == "__main__":
# Tool calls as a model might propose them while helping alice with a ticket.
proposed = [
("tickets.read", {"ticket_id": "T-42"}),
("orders.read", {"order_id": "A-1001"}),
("orders.refund", {"order_id": "A-1001", "amount": 240}),
("orders.refund", {"order_id": "A-1001", "amount": 80}),
("shell.exec", {"command": "rm -rf /"}),
]
for tool, args in proposed:
print(tool, args, "->", call_tool("support-agent", "alice", tool, args))

print()
print("bob:", call_tool("support-agent", "bob", "tickets.read", {"ticket_id": "T-42"}))

L'exécution affiche :

tickets.read {'ticket_id': 'T-42'} -> {'id': 'T-42', 'subject': 'Refund request', 'order_id': 'A-1001'}
orders.read {'order_id': 'A-1001'} -> {'id': 'A-1001', 'total': 240}
orders.refund {'order_id': 'A-1001', 'amount': 240} -> {'error': 'permission_denied', 'reason': "support-agent may not call orders.refund with {'order_id': 'A-1001', 'amount': 240}"}
orders.refund {'order_id': 'A-1001', 'amount': 80} -> {'order_id': 'A-1001', 'refunded': 80}
shell.exec {'command': 'rm -rf /'} -> {'error': 'permission_denied', 'reason': "support-agent may not call shell.exec with {'command': 'rm -rf /'}"}

bob: {'error': 'permission_denied', 'reason': 'bob may not call tickets.read, so an agent acting for them may not either'}

Le remboursement de 240 est refusé même si alice peut rembourser n'importe quel montant, car l'agent ne le peut pas. Bob n'a aucun rôle, donc l'agent ne peut rien faire pour lui. Renvoyer le refus comme résultat de l'outil, au lieu de le signaler à l'utilisateur, permet au modèle d'expliquer la limite ou de confier le cas à une personne.

5. Utilisation dans un serveur MCP​

Dans un serveur MCP utilisant OAuth, le jeton d'accès indique déjà les deux identités : le client OAuth est l'agent, et le sujet du jeton est l'utilisateur qui l'a autorisé. Avec le SDK Python officiel (version 2), lisez-les avec get_access_token() et vérifiez chaque appel d'outil :

server.py
from mcp.server.auth.middleware.auth_context import get_access_token
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

from tools import ToolDenied, authorize_tool_call

mcp = MCPServer("support-tools")


def authorize(tool: str, args: dict) -> None:
"""Check the tool call against Casbin for the OAuth client (the agent) and the user it acts for."""
token = get_access_token()
if token is None or token.subject is None:
raise ToolError("not authenticated")
try:
authorize_tool_call(token.client_id, token.subject, tool, args)
except ToolDenied as e:
raise ToolError(str(e)) from e


@mcp.tool()
def refund_order(order_id: str, amount: float) -> dict:
"""Refund part or all of an order."""
authorize("orders.refund", {"order_id": order_id, "amount": amount})
return {"order_id": order_id, "refunded": amount}


@mcp.tool()
def read_ticket(ticket_id: str) -> dict:
"""Read a support ticket."""
authorize("tickets.read", {"ticket_id": ticket_id})
return {"id": ticket_id, "subject": "Refund request"}

Le lancement de ToolError transforme le refus en un résultat d'outil avec isError défini, que les clients MCP renvoient au modèle. Le client_id du jeton doit correspondre aux noms des agents dans votre politique ; enregistrez chaque agent comme son propre client OAuth afin de pouvoir lui attribuer ses propres permissions et les révoquer séparément.

Notes de conception​

  • Refus par défaut. Un outil non mentionné par aucune règle ne peut être appelé, de sorte qu'un nouvel outil est indisponible pour les agents jusqu'à ce que vous l'accordiez.
  • Moindre privilège par agent. Attribuez à chaque agent son propre rôle plutôt que de partager un seul rôle puissant. Le triage-agent ci-dessus ne peut pas toucher aux commandes même si une invite lui demande.
  • Vérifier les arguments, pas seulement les noms. Les limites sur les montants, les destinataires, les chemins ou les régions appartiennent aux conditions. Validez les types d'arguments avant la vérification : la condition compare ce que le modèle a envoyé, et comparer la chaîne "500" avec un nombre provoque une erreur au lieu de renvoyer une décision.
  • Modifier les permissions sans redéploiement. Les règles sont des données : enforcer.add_policy(...), enforcer.add_role_for_user(...), ou des modifications via un adaptateur prennent effet lors du prochain appel. Utilisez un observateur lorsque plusieurs processus servent les agents.
  • Audit. enforcer.enforce_ex(...) renvoie la règle qui a autorisé un appel ; journalisez-la à côté de l'appel d'outil.
  • Filtrer la liste des outils. Appelez la même vérification lors de la liste des outils, afin que le modèle ne se voie même pas proposer des outils qu'il ne peut pas utiliser. Cela économise également des tokens.

Étapes suivantes​

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.