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 :
- 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.
- 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.globMatchfait correspondre les noms d'outils avec des caractères génériques tels quetickets.*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-agentpeut utiliser tous les outils de ticket, lire les commandes et effectuer des remboursements d'au plus 100 par appel. La conditionr.args.amount <= 100est évaluée sur les arguments produits par le modèle.- Tout rôle qui hérite de
any-agentse 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-staffest un rôle humain ;alicele possède.triage-agentest un second agent plus restreint qui ne peut que lire et étiqueter les tickets.
É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.
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 :
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-agentci-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
- ABAC explique en détail les conditions et
eval(). - RBAC avec domaines donne aux agents différentes permissions par espace de travail ou tenant.
- Effector décrit les effets allow, deny et priority.
- Choisir un modèle de contrôle d'accès compare RBAC, ABAC et ReBAC.
Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.