Como funciona a autenticação por toolbox no Microsoft Foundry

A autenticação da caixa de ferramentas no Microsoft Foundry determina como as ferramentas se autenticam junto de serviços a jusante. As definições de autenticação são configuradas nas ligações do projeto, permitindo aos agentes usar acesso anónimo, credenciais partilhadas, identidades de serviço ou a identidade de um utilizador iniciado sem implementar lógica de autenticação no código do agente.

Este artigo explica como funciona a autenticação por toolbox e mostra como configurar o passthrough de identidade OAuth para um servidor MCP privado e o Work IQ, preservando as permissões e limites de acesso de cada utilizador.

Uma caixa de ferramentas centraliza a autenticação na ligação. A autenticação é uma propriedade da ligação, não um código no seu agente. Quando ligas uma ferramenta, selecionas um tipo de autenticação e o Foundry trata da obtenção, troca, atualização e injeção de tokens do lado do serviço. O seu código de agente mantém-se focado na lógica de negócio em vez dos fluxos de autenticação.

Por que a autenticação por utilizador é difícil de construir por si próprio

Se configurar você mesmo o acesso por utilizador a ferramentas protegidas pelo Entra, fica responsável por uma infraestrutura de segurança crítica em que é fácil cometer erros subtis:

  1. Implemente você mesmo o isolamento de tokens para cada utilizador. Deve particionar corretamente as caches de tokens por utilizador e inquilino. Uma chave de cache errada pode expor silenciosamente o acesso de um utilizador à API a jusante a outro utilizador, um erro que passa em todos os testes funcionais.
  2. Gerir o consentimento e o ciclo de vida por utilizador, por recurso. É necessário detetar falhas relacionadas com o consentimento, como AADSTS65001, encaminhar os utilizadores pelo processo de consentimento, renovar tokens expirados e gerir corretamente novas tentativas após erros 401/403 para cada API em cada agente que escrever.
  3. Absorver complexidade que escale linearmente com ferramentas e agentes. Cada nova ferramenta acrescenta outro âmbito, outra troca de tokens, outra entrada de cache, outro fluxo de consentimento, outro fluxo de nova tentativa e outro fluxo de cabeçalhos. À medida que se escala para centenas de ferramentas e milhares de agentes, reconstrói a mesma canalização frágil vezes sem conta.

As duas identidades em cada chamada de ferramenta

O modelo mental a que se deve agarrar: há sempre duas identidades em jogo, e tudo o que é difícil na autenticação por utilizador reside em mantê-las corretas, separadas e nunca cruzadas entre utilizadores simultâneos.

  • Fronteira entre o agente e a caixa de ferramentas (a estável). O agente autentica-se na plataforma com a sua própria identidade de agente. Esta identidade limita o acesso à caixa de ferramentas em si, não às ferramentas individuais dentro dela.
  • Fronteira entre a ferramenta e os dados (a por utilizador). Para a chamada de dados propriamente dita, o Foundry fornece ao serviço downstream credenciais que representam o utilizador com sessão iniciada. Dependendo do tipo de autenticação, essas credenciais provêm de um fluxo de autorização OAuth ou de um token de acesso do Microsoft Entra destinado a um público específico. O serviço a jusante devolve apenas o que o utilizador pode aceder e respeita as suas permissões e etiquetas de sensibilidade.

Como um conjunto de ferramentas gere a autenticação

Um conjunto de ferramentas retira do seu agente toda a responsabilidade pela autenticação e coloca-a na ligação:

  • A autenticação está na conexão, não no agente. Escolhes um tipo de autenticação uma vez, quando ligas uma ferramenta. O código do agente continua sem autenticação.
  • A fundição trata de todo o fluxo. Dependendo do que uma ferramenta precisa, o Foundry armazena e injeta chaves API, obtém credenciais para identidades de serviço, completa a autorização OAuth ou fornece um token de acesso Microsoft Entra específico para o público. O Foundry isola as credenciais de cada utilizador das de outros utilizadores.
  • Basta construir lógica de negócio. O fluxo de autenticação nunca foi algo que tivesse de ser desenvolvido por si.
O encargo do faça-você-mesmo O que uma caixa de ferramentas faz em vez disso
Isolamento de token por utilizador A Foundry isola automaticamente os tokens para cada autor da chamada. Não há nenhuma chave de cache que possa estar errada.
Consentimento e gestão do ciclo de vida, por utilizador e por recurso A Foundry gere o fluxo de consentimento e o ciclo de vida dos tokens para cada utilizador, incluindo a aquisição e atualização dos tokens após a concessão do consentimento necessário.
Autenticação reimplementada por ferramenta e por equipa Cria um kit de ferramentas com as respetivas ferramentas e autenticação uma vez e depois reutiliza-o em todos os agentes e ambientes de execução.

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

Escolhe o tipo de autenticação quando cria a ligação, no portal, com a CLI do Azure Developer ou através da API REST. Nunca em código de agente. Cada tipo de autenticação determina de quem a identidade chega à ferramenta:

authType Cuja identidade chega à ferramenta Usa-o para
none Anonymous Servidores públicos (por exemplo, o servidor MCP do Microsoft Learn).
custom-keys Uma chave ou cabeçalho API armazenado SaaS baseado em teclas. O agente nunca vê o segredo.
project-managed-identity Identidade gerida do projeto Chamadas de serviço para serviço sem contexto de utilizador.
agentic-identity A própria identidade do agente Auditoria por agente e mínimo privilégio.
oauth2 O utilizador que completa a autorização OAuth Serviços compatíveis com OAuth, incluindo Work IQ e servidores MCP parceiros (por exemplo, Vercel).
user-entra-token O utilizador da Microsoft Entra com sessão Serviços Microsoft geridos que requerem um token Entra específico para um público, como pontos finais privados do espaço de trabalho para agentes de dados do Fabric.

Tanto oauth2 como user-entra-token suportam acesso por utilizador, mas obtêm as credenciais de forma diferente. Com oauth2, o utilizador completa um fluxo de autorização 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 específico do público que representa o utilizador com sessão iniciada. Use o tipo de autenticação exigido pelo serviço.

Configure uma ligação para cada tipo de autenticação

Registar cada ligação com azd ai connection create. A forma do comando é sempre a mesma; As bandeiras diferem consoante o 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

Guia: Passagem de identidade OAuth

Este exemplo liga duas ferramentas protegidas pela Microsoft Entra para acesso por utilizador: um servidor privado de encomendas MCP e o Work IQ. Ambos usam o passthrough de identidade OAuth, pelo que cada chamada a jusante é executada como o utilizador que autoriza a ligação.

1. Criar uma ligaçã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 referencia a sua ligação por ID. Essa única referência é toda a diferença entre funcionar como uma conta de serviço partilhada e agir em nome do utilizador iniciado sessão. O teu agente não precisa de um corretor de tokens nem de um cache de tokens por utilizador.

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 atualizado de ligação ao projeto Toolbox e o exemplo Work IQ. O primeiro exemplo cria uma caixa de ferramentas apoiada por MCP que utiliza uma ligação de projeto e a anexa a um agente. O segundo exemplo mostra como referenciar a ligação ao projeto Work IQ.

3. Ligar o agente à caixa de ferramentas

O agente liga-se ao endpoint único do consumidor da toolbox, que serve sempre a versão predefinida. O agente autentica-se na plataforma com a sua própria identidade. Para cada ferramenta, o Foundry fornece credenciais que representam o utilizador que completou a autorização OAuth. O agente não possui código de autenticação específico de 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],
)

O Foundry gera um link de consentimento na primeira vez que um determinado utilizador precisa de autorizar uma ferramenta. Depois de consentirem, as chamadas subsequentes utilizam as credenciais desse utilizador. O utilizador pode precisar de autorizar novamente a ferramenta se o token de atualização expirar ou for revogado.

Note

Os consumidores de um agente que utiliza a transmissão da identidade OAuth têm de ter, pelo menos, a função de Consumidor do Agente Foundry no projeto. O locatário do Microsoft Entra do utilizador tem de corresponder ao locatário do seu projeto do Foundry; a troca de tokens entre locatários não é suportada.

Para além do passthrough: o que mais uma caixa de ferramentas lhe oferece

Como a autenticação e o tráfego das ferramentas passam pela toolbox, beneficia de mais do que uma gestão de identidade simplificada:

  • Limites de IA responsável. Os guardrails filtram as entradas e saídas de todas as ferramentas, por isso uma resposta MCP não confiável não pode contrabandear injeção rápida ou conteúdo inseguro de volta para o agente.
  • Traz o teu próprio gateway de IA. Coloque os seus servidores MCP no API Management do Azure (APIM) para limitação de taxas, registo e política de rede.
  • Versionamento. Crie e teste uma nova versão da caixa de ferramentas e depois promova-a para o padrão. Cada agente que aponta para o endpoint do consumidor recolhe automaticamente a versão promovida, sem alterações no código.

Conteúdo relacionado

  • Last updated on