Перейти к основному содержимому

Авторизация для ИИ-агентов и инструментов MCP

ИИ-агент во время выполнения решает, какие инструменты вызывать и с какими аргументами. Модель может ошибаться, и её можно обмануть текстом, который она читает в тикете, веб-странице или документе. Авторизация должна находиться вне модели, в точке выполнения вызова инструмента, и отвечать на два вопроса:

  1. Может ли этот агент вызвать этот инструмент с этими аргументами? Вспомогательный ассистент поддержки может читать тикеты и оформлять небольшие возвраты средств, но никогда не должен выполнять команды оболочки.
  2. Может ли пользователь, за которого он действует, это сделать? Агент, действующий от имени кого-либо, не должен получать больше доступа, чем есть у этого человека.

Casbin обрабатывает оба случая с одной моделью и одной политикой, так же, как он обрабатывает пользователей. На этой странице сначала представлены правила, затем они интегрированы в простой цикл вызова инструментов и в сервер MCP. Код написан на Python. Модель и политика также работают в других реализациях Casbin; в Go передавайте аргументы как структуру и используйте имена её экспортируемых полей в условиях, например r.args.Amount.

1. Установка​

pip install pycasbin

2. Написание модели​

Сохраните это как 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: вызывающий объект (агент или пользователь), имя инструмента и аргументы инструмента в виде объекта.
  • p = sub, tool, cond, eft: каждое правило указывает роль, шаблон имени инструмента, необязательное условие для аргументов и разрешает или запрещает действие.
  • g = _, _: агенты и пользователи имеют роли, и роли могут наследовать другие роли.
  • globMatch сопоставляет имена инструментов с подстановочными знаками, такими как tickets.* или *.delete.
  • Эффект политики разрешает вызов, если какое-то правило его разрешает и ни одно правило не запрещает, поэтому правило запрета всегда имеет приоритет.

3. Написание политики​

Сохраните это как 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

Читая её сверху вниз:

  • support-agent может использовать любой инструмент тикетов, читать заказы и оформлять возвраты на сумму не более 100 за вызов. Условие r.args.amount <= 100 проверяется по аргументам, сгенерированным моделью.
  • Всем ролям, наследующим any-agent, запрещены инструменты shell и любые инструменты, оканчивающиеся на .delete, независимо от других выданных разрешений. Здесь следует размещать ограничения (guardrails), применимые ко всем агентам.
  • support-staff — это роль человека; она назначена пользователю alice.
  • triage-agent — второй, более узкий агент, который может только читать и маркировать тикеты.
подсказка

Строковые литералы в условиях пишите в одинарных кавычках, например: r.args.region == 'eu'. Если в условии нужна запятая, заключите всё поле в двойные кавычки.

4. Проверка каждого вызова инструмента​

Функция authorize_tool_call выполняет две проверки. Собственные разрешения агента ограничивают то, что он может делать в принципе, а разрешения пользователя ограничивают то, что агент может сделать для этого конкретного пользователя. Выполняются только те вызовы, которые проходят обе проверки.

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"}))

При запуске выводится:

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

Возврат суммы 240 отклоняется, даже если alice может оформлять возвраты на любую сумму, потому что агенту это запрещено. У Bob нет роли, поэтому агент не может ничего для него сделать. Возвращение отказа как результата инструмента, вместо генерации исключения для пользователя, позволяет модели объяснить ограничение или передать случай человеку.

5. Использование в MCP-сервере​

В MCP-сервере, использующем OAuth, токен доступа уже содержит обе идентичности: клиент OAuth — это агент, а субъект токена — пользователь, который его авторизовал. С официальным Python SDK (версия 2) считайте их через get_access_token() и проверяйте каждый вызов инструмента:

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

Генерация ToolError превращает отказ в результат инструмента с установленным флагом isError, который MCP-клиенты передают обратно модели. Поле client_id токена должно совпадать с именами агентов в вашей политике; регистрируйте каждого агента как отдельного OAuth-клиента, чтобы выдавать ему собственные разрешения и отзывать их независимо.

Заметки по проектированию​

  • Запрет по умолчанию. Инструмент, о котором не упоминает ни одно правило, не может быть вызван, поэтому новый инструмент недоступен агентам, пока вы явно не предоставите разрешение.
  • Минимальные привилегии для каждого агента. Выдавайте каждому агенту собственную роль, а не разделяйте одну мощную роль. Описанный выше triage-agent не может трогать заказы, даже если об этом просит промпт.
  • Проверяйте аргументы, а не только имена. Ограничения на суммы, получателей, пути или регионы должны находиться в условиях. Проверяйте типы аргументов перед проверкой: условие сравнивает то, что отправила модель, и сравнение строки "500" с числом вызывает ошибку вместо принятия решения.
  • Изменение разрешений без переразвертывания. Правила — это данные: enforcer.add_policy(...), enforcer.add_role_for_user(...) или правки через adapter вступают в силу при следующем вызове. Используйте watcher, если несколько процессов обслуживают агентов.
  • Аудит. enforcer.enforce_ex(...) возвращает правило, которое разрешило вызов; логируйте его вместе с вызовом инструмента.
  • Фильтрация списка инструментов. Выполняйте ту же проверку при перечислении инструментов, чтобы модель даже не получала предложений использовать инструменты, которые ей недоступны. Это также экономит токены.

Следующие шаги​

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