본문으로 건너뛰기

Authorization for AI Agents and MCP Tools

AI 에이전트는 런타임에 어떤 도구를 호출하고 어떤 인자를 사용할지 결정합니다. 모델은 오류를 범할 수 있으며, 티켓, 웹 페이지 또는 문서에서 읽은 텍스트에 의해 속아 넘어갈 수도 있습니다. 인증은 모델 외부, 즉 도구 호출이 실행되는 지점에 위치해야 하며 다음 두 질문에 답해야 합니다:

  1. 이 에이전트가 이 인자로 이 도구를 호출해도 되는가? 지원 어시스턴트는 티켓을 읽고 소액 환불을 처리할 수 있지만, 셸 명령어를 실행해서는 안 됩니다.
  2. 대신 행동하는 사용자가 이를 수행할 권한이 있는가? 누군가를 대신해 행동하는 에이전트는 그 사람보다 더 많은 접근 권한을 가져서는 안 됩니다.

Casbin은 사용자를 처리하는 것과 동일한 방식으로 하나의 모델과 하나의 정책으로 두 가지를 모두 처리합니다. 이 페이지에서는 먼저 규칙을 설명한 후, 일반 도구 호출 루프와 MCP 서버에 연결하는 방법을 보여줍니다. 코드는 Python입니다. 모델과 정책은 다른 Casbin 구현체에서도 작동하며, Go에서는 인자를 구조체로 전달하고 조건에서 내보낸 필드 이름(예: r.args.Amount)을 사용합니다.

1. Install​

pip install pycasbin

2. Write the model​

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. Write the policy​

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를 상속하는 모든 역할은 셸 도구와 .delete로 끝나는 모든 도구가 거부되며, 다른 권한이 부여되더라도 동일합니다. 모든 에이전트에 적용되는 가드레일은 여기에 두세요.
  • 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'}

alice는 금액 제한 없이 환불할 수 있지만, 에이전트는 그렇지 않으므로 240의 환불이 거부됩니다. Bob은 역할이 없으므로 에이전트가 그를 위해 아무것도 할 수 없습니다. 거부를 사용자에게 직접 전달하지 않고 도구 결과로 반환하면 모델이 제한 사항을 설명하거나 해당 사례를 사람에게 넘길 수 있습니다.

5. MCP 서버에서 사용​

OAuth를 사용하는 MCP 서버에서는 액세스 토큰이 이미 두 신원을 알려줍니다. 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 클라이언트로 등록하여 고유한 권한을 부여하고 개별적으로 취소할 수 있도록 하세요.

설계 노트​

  • 기본 거부(Default deny). 어떤 규칙에서도 언급되지 않은 도구는 호출할 수 없으므로, 권한을 부여하기 전까지는 새로운 도구가 에이전트에게 사용 불가 상태입니다.
  • 에이전트별 최소 권한. 하나의 강력한 역할을 공유하기보다 각 에이전트에 고유한 역할을 부여하세요. 위의 triage-agent는 프롬프트에서 요청하더라도 주문에 접근할 수 없습니다.
  • 이름뿐만 아니라 인수 확인. 금액, 수신자, 경로 또는 지역에 대한 제한은 조건(condition)에 포함시켜야 합니다. 검사 전에 인수 유형을 검증하세요. 조건은 모델이 보낸 내용을 비교하며, 문자열 "500"과 숫자를 비교하면 결정 대신 오류가 발생합니다.
  • 재배포 없이 권한 변경. 규칙은 데이터입니다: enforcer.add_policy(...), enforcer.add_role_for_user(...) 또는 adapter를 통한 편집은 다음 호출부터 반영됩니다. 여러 프로세스가 에이전트를 서비스하는 경우 watcher를 사용하세요.
  • 감사(Audit). enforcer.enforce_ex(...)는 호출을 허용한 규칙을 반환하므로, 도구 호출 옆에 이를 기록하세요.
  • 도구 목록 필터링. 도구 목록을 나열할 때 동일한 검사를 호출하여 모델이 사용할 수 없는 도구를 제공받지 않도록 하세요. 이는 또한 토큰 사용을 절약합니다.

다음 단계​

  • ABAC에서 조건과 eval()에 대해 자세히 설명합니다.
  • RBAC with domains를 통해 워크스페이스 또는 테넌트별로 에이전트에 다른 권한을 부여할 수 있습니다.
  • Effector는 allow, deny 및 우선순위 효과를 설명합니다.
  • Choosing an access control model은 RBAC, ABAC 및 ReBAC을 비교합니다.

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