Como funciona a autenticação de caixa de ferramentas no Microsoft Foundry

A autenticação da caixa de ferramentas no Microsoft Foundry determina como as ferramentas se autenticam em serviços downstream. As configurações de autenticação são configuradas em conexões de projeto, permitindo que os agentes usem acesso anônimo, credenciais compartilhadas, identidades de serviço ou a identidade de um usuário conectado sem implementar a lógica de autenticação no código do agente.

Este artigo explica como funciona a autenticação de caixa de ferramentas e mostra como configurar a passagem de identidade OAuth para um servidor MCP privado e o IQ de trabalho, preservando as permissões e os limites de acesso de cada usuário.

Uma caixa de ferramentas centraliza a autenticação na conexão. A autenticação é uma propriedade da conexão, não do código em seu agente. Ao conectar uma ferramenta, você seleciona um tipo de autenticação e o Foundry manipula a aquisição, troca, atualização e injeção de token no lado do serviço. O código do agente permanece focado na lógica de negócios em vez de fluxos de autenticação.

Por que a autenticação por usuário é difícil de criar por conta própria

Se você mesmo implementar o acesso por usuário às ferramentas protegidas pelo Entra, assumirá uma infraestrutura crítica de segurança na qual é fácil cometer erros sutis:

  1. Implemente você mesmo o isolamento de tokens por usuário. Você deve particionar caches de token corretamente por usuário e locatário. Uma chave de cache errada pode vazar silenciosamente o acesso à API downstream de um usuário para outro usuário, um bug que passa em todos os testes funcionais.
  2. Gerenciar o consentimento e o ciclo de vida por usuário, por recurso. Você precisa detectar falhas de consentimento, como AADSTS65001, conduzir os usuários pelo fluxo de consentimento, atualizar tokens expirados e tratar corretamente as novas tentativas após erros 401/403 para cada API em cada agente que você criar.
  3. Absorva a complexidade que cresce linearmente com ferramentas e agentes. Cada nova ferramenta adiciona outro escopo, troca de tokens, entrada de cache, caminho de consentimento, caminho de repetição e caminho de cabeçalho. À medida que você expande para centenas de ferramentas e milhares de agentes, reconstrói a mesma infraestrutura frágil repetidamente.

As duas identidades em cada chamada de ferramenta

O modelo mental a ser mantido: há sempre duas identidades em jogo e tudo o que é difícil sobre a autenticação por usuário reside em mantê-las corretas, separadas e nunca cruzadas entre usuários simultâneos.

  • Fronteira entre o agente e a caixa de ferramentas (a estável). O agente é autenticado na plataforma com sua própria identidade de agente. Essa identidade porta o acesso à caixa de ferramentas em si, não às ferramentas individuais dentro dela.
  • Limite entre ferramenta e dados (o limite por usuário). Para a chamada de dados real, o Foundry fornece ao serviço downstream credenciais que representam o usuário conectado. Dependendo do tipo de autenticação, essas credenciais vêm de um fluxo de autorização OAuth ou de um token de acesso do Microsoft Entra específico para o público. O serviço downstream retorna apenas o que o usuário pode acessar e respeita suas permissões e rótulos de confidencialidade.

Como uma caixa de ferramentas lida com a autenticação

Um conjunto de ferramentas transfere toda a responsabilidade pela autenticação do seu agente para a conexão:

  • A autenticação fica na conexão, não no agente. Você escolhe um tipo de autenticação uma vez, quando conecta uma ferramenta. O código do agente permanece livre de autenticação.
  • Foundry gerencia todo o fluxo. Dependendo do que uma ferramenta precisa, o Foundry armazena e injeta chaves de API, obtém credenciais para identidades de serviço, conclui a autorização do OAuth ou fornece um token de acesso Microsoft Entra específico ao público. Foundry isola as credenciais de cada usuário das de outros usuários.
  • Você só desenvolve a lógica de negócio. O fluxo de autenticação nunca foi algo que você devesse desenvolver.
O fardo DIY O que uma caixa de ferramentas faz em vez disso
Isolamento de token por usuário Foundry isola os tokens de cada chamador automaticamente. Não há chave de cache para configurar incorretamente.
Consentimento e tratamento do ciclo de vida, por usuário e por recurso A Foundry gerencia o fluxo de consentimento e o ciclo de vida do token para cada usuário, incluindo a aquisição e atualização de tokens após a concessão do consentimento necessário.
Autenticação reimplementada por ferramenta e por equipe Você cria uma caixa de ferramentas com suas ferramentas e autenticação uma vez e, em seguida, reutiliza-a em todos os agentes e runtime.

Definir o tipo de autenticação na conexão

Você escolhe o tipo de autenticação ao criar a conexão, no portal, com a CLI do Desenvolvedor Azure ou por meio da API REST. Nunca no código do agente. Cada tipo de autenticação determina qual identidade é transmitida à ferramenta:

authType Cuja identidade atinge a ferramenta Use-o para
none Anônimo Servidores públicos (por exemplo, o servidor MCP do Microsoft Learn).
custom-keys Um cabeçalho ou chave de API armazenado SaaS baseado em chave. O agente nunca vê o segredo.
project-managed-identity A identidade gerenciada do projeto Chamadas de serviço a serviço sem contexto de usuário.
agentic-identity A própria identidade do agente Auditoria por agente e privilégio mínimo.
oauth2 O usuário que conclui a autorização do OAuth Serviços compatíveis com OAuth, incluindo Work IQ e servidores MCP de parceiros (por exemplo, Vercel).
user-entra-token O usuário Microsoft Entra conectado Serviços gerenciados da Microsoft que exigem um token do Entra específico para o público, como pontos de extremidade privados do workspace para o agente de dados do Fabric.

Tanto oauth2 quanto user-entra-token suportam acesso por usuário, mas obtêm credenciais de forma diferente. Com oauth2, o usuário conclui um fluxo de autorização do OAuth e o Foundry armazena e atualiza as credenciais resultantes. Com user-entra-token, o Foundry fornece ao serviço downstream um token de acesso do Microsoft Entra destinado a um público específico, que representa o usuário conectado. Use o tipo de autenticação exigido pelo serviço.

Configurar uma conexão para cada tipo de autenticação

Registrar cada conexão com azd ai connection create. A forma de comando é sempre a mesma; os sinalizadores diferem por tipo de autenticação. Use --kind remote-tool para servidores MCP e A2A.

azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://public-mcp.example.com/mcp \
  --auth-type none

Passo a passo: passagem de identidade OAuth

Este exemplo conecta duas ferramentas protegidas por Microsoft Entra para acesso por usuário: um servidor MCP de pedidos privados e o IQ de trabalho. Ambos usam a passagem de identidade OAuth, para que cada chamada downstream seja executada como o usuário que autoriza a conexão.

1. Criar uma conexão para cada ferramenta

# Private orders MCP: OAuth identity passthrough
azd ai connection create orders-mcp \
  --kind remote-tool \
  --target https://orders-mcp.example.com/mcp \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "openid offline_access orders.read"

# Work IQ: OAuth identity passthrough
azd ai connection create workiq-conn \
  --kind remote-a2a \
  --target https://workiq.svc.cloud.microsoft/a2a/ \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask offline_access"

2. Adicionar ambas as ferramentas a uma caixa de ferramentas

Cada ferramenta faz referência à sua conexão por ID. Essa única referência é toda a diferença entre executar como uma conta de serviço compartilhada e agir em nome do usuário conectado. Seu agente não precisa de um broker de token ou de um cache de token por usuário.

Este exemplo requer azure-ai-projects (Python) ou @azure/ai-projects (TypeScript) versão 2.3.0 ou posterior.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WorkIQPreviewToolboxTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
orders_connection = project.connections.get("orders-mcp")
workiq_connection = project.connections.get("workiq-conn")

toolbox_version = project.toolboxes.create_version(
    name="employee-toolbox",
    description="Private orders MCP + Work IQ, both via OAuth identity passthrough.",
    tools=[
        MCPToolboxTool(
            server_label="orders",
            server_url="https://orders-mcp.example.com/mcp",
            require_approval="never",
            project_connection_id=orders_connection.id,
        ),
        WorkIQPreviewToolboxTool(project_connection_id=workiq_connection.id),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

Para JavaScript, consulte o exemplo de conexão de projeto do toolbox mantido e o exemplo do Work IQ. O primeiro exemplo cria um kit de ferramentas baseado em MCP que usa uma conexão de projeto e o anexa a um agente. O segundo exemplo mostra como referenciar a conexão do projeto Work IQ.

3. Conectar o agente à caixa de ferramentas

O agente se conecta ao endpoint de consumidor único da toolbox, que sempre disponibiliza a versão padrão. O agente é autenticado na plataforma com sua própria identidade. Para cada ferramenta, o Foundry fornece credenciais que representam o usuário que concluiu a autorização do OAuth. O agente não contém código de autenticação específico para cada ferramenta.

from azure.identity import DefaultAzureCredential
from agent_framework import FoundryToolbox

# Agent-to-toolbox identity: the agent's own credential, scoped to the platform
credential = DefaultAzureCredential()
, timeout=120.0)

# Consumer endpoint always resolves to the toolbox's default version
CONSUMER_URL = f"{endpoint}/toolboxes/employee-toolbox/mcp?api-version=v1"

toolbox = FoundryToolbox(
    name="employee_toolbox",
    url=CONSUMER_URL,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="employee-agent",
    instructions="Help employees with their orders and Microsoft 365 context.",
    tools=[toolbox],
)

A Foundry gera um link de consentimento na primeira vez que um determinado usuário precisa autorizar uma ferramenta. Após o consentimento, as chamadas subsequentes usam as credenciais desse usuário. Talvez o usuário precise autorizar a ferramenta novamente se o token de atualização expirar ou for revogado.

Note

Os consumidores de um agente que usa a passagem de identidade OAuth precisam, pelo menos, da função consumidor do Foundry Agent no projeto. O locatário Microsoft Entra do usuário deve corresponder ao locatário do seu projeto do Foundry; não há suporte para troca de token entre locatários.

Além do pass-through: o que mais um kit de ferramentas oferece

Como a autenticação e o tráfego das ferramentas passam pela toolbox, você obtém mais do que um gerenciamento de identidade simplificado:

  • Salvaguardas para IA responsável. Os guardrails exibem as entradas e saídas de cada ferramenta, de modo que uma resposta MCP não confiável não pode contrabandear a injeção de prompt ou o conteúdo não seguro de volta para o agente.
  • Traga seu próprio gateway de IA. Coloque seus servidores MCP atrás do Gerenciamento de API do Azure (APIM) para limitação de taxa, registro em log e política de rede.
  • Controle de versão.. Crie e teste uma nova versão da caixa de ferramentas e promova-a como padrão. Cada agente que aponta para o endpoint do consumidor adota automaticamente a versão promovida, sem alterações no código.

Conteúdo relacionado

  • Last updated on