Proteger chamadas de ferramenta OpenAPI do Serviço do Foundry Agent

O Foundry Agent Service pode chamar um endpoint OpenAPI de App Service anonimamente ou com identidade gerenciada. Use a identidade gerenciada quando a autenticação do App Service protege o endpoint.

Este cenário contém duas direções de identidade gerenciadas independentes:

• Quando o App Service chama o Foundry, o chamador é a identidade gerenciada atribuída pelo sistema do App Service. O controle de acesso baseado em função (RBAC) do Azure no recurso ou projeto Foundry autoriza a chamada.
• Quando o Foundry chama o endpoint OpenAPI do Serviço de Aplicativos, o chamador é a identidade gerenciada atribuída ao sistema de recurso Foundry pai. A autenticação do App Service, a validação de token e as listas de permissões autorizam a chamada.

O aplicativo Microsoft Entra de autenticação do App Service é o recurso de API protegido. Isso não substitui nenhuma das chamadas de identidade gerenciada.

A tabela a seguir resume as identidades e aplicações nesse cenário.

Pré-requisitos

• Um aplicativo do Serviço de Aplicativo com pontos de extremidade do OpenAPI. Se você precisar adicionar a funcionalidade OpenAPI ao seu aplicativo, confira um dos seguintes tutoriais:

  • Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Serviço de Agente da Fábrica (.NET)
  • Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Serviço de Agente da Fábrica (Java)
  • Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Serviço de Agente da Fábrica (Python)
  • Adicionar um aplicativo do Azure App Service como uma ferramenta no Serviço do Foundry Agent (Node.js)

• Um projeto da Microsoft Foundry onde você adiciona seu aplicativo como uma ferramenta OpenAPI.

Encontre os IDs de identidade gerenciada do recurso Foundry principal

O Serviço de Agente do Foundry usa a identidade gerenciada atribuída pelo sistema do recurso Foundry pai ao chamar uma ferramenta OpenAPI. Ele não usa a identidade gerenciada do projeto Foundry para esse pedido.

Você precisa de dois identificadores para a identidade do recurso pai:

• ID do aplicativo (ID do cliente): Aparece na declaração azp do token de acesso e é usado para a verificação de aplicativo cliente permitido na autenticação do App Service.
• ID do objeto (principal): Aparece na reivindicação do oid token e é usada quando a autenticação do App Service restringe o acesso a identidades específicas.

1. No portal da Foundry, abra seu projeto e depois selecione Gerenciar no menu superior.

2. Selecione o recurso pai em detalhes do Project e depois selecione Abrir no portal do Azure.

3. No menu esquerdo do recurso Foundry, selecione Gerenciamento de Recursos>Identidade.

4. Em Sistema atribuído, copie o valor da ID do objeto (principal) para mais tarde.

5. No portal do Azure, pesquise e selecione a ID do Microsoft Entra.

6. Na caixa de pesquisa, pesquise a ID do objeto copiada e selecione-a nos resultados da pesquisa.

7. Na página Visão geral , copie o valor da ID do aplicativo.

   O ID do Objeto é o mesmo mostrado para a identidade gerenciada atribuída pelo sistema. Salve tanto o ID da aplicação quanto o ID do objeto para configurar a autenticação do App Service.

Configurar a autenticação do Microsoft Entra para seu aplicativo

1. No portal do Azure, navegue até seu aplicativo do Serviço de Aplicativo.

2. No menu à esquerda do aplicativo, selecione Configurações>Autenticação e escolha Adicionar o provedor de identidade.

3. Na página Adicionar um provedor de identidade , selecione a Microsoft como o provedor de identidade para criar um novo registro de aplicativo.

4. Para restringir o acesso, selecione Exigir autenticação.

5. Em verificações adicionais, para o requisito de aplicativo cliente, selecione Permitir solicitações de aplicativos cliente específicos.

6. Selecione o ícone de lápis e configure as aplicações clientes permitidas:

   • Adicione o ID do aplicativo que você copiou em Localizar os IDs de identidade gerenciada do recurso Foundry pai. Este ID permite os tokens solicitados pela identidade do recurso Foundry pai.
   • Se o aplicativo suportar login interativo do navegador, adicione também o ID de aplicativo (cliente) do aplicativo Microsoft Entra de autenticação do App Service. Esse ID permite tokens emitidos para a aplicação web durante o login do usuário. Se você estiver criando um novo registro de app, adicione esse ID depois de criar o provedor de identidade.

7. Configure o requisito de identidade:

   • Para a política mais restrita em um endpoint chamado apenas pelo Foundry, selecione Permitir solicitações de identidades específicas. Selecione o ícone do lápis e adicione o ID do objeto da identidade do recurso pai do Foundry.
   • Se o aplicativo também suportar login interativo do navegador, selecione Permitir solicitações de qualquer identidade para que os usuários locatários não sejam bloqueados. Essa configuração não permite acesso anônimo. As solicitações ainda devem conter um token válido de uma aplicação cliente permitida e do locatário configurado.

8. Para o requisito do Inquilino, selecione Permitir solicitações apenas do inquilino emissor. A identidade do recurso Foundry principal e quaisquer usuários que fazem login devem estar nesse tenant.

9. Configurar requisições não autenticadas:

   • Se o app atender apenas clientes de API, selecione HTTP 401 Não Autorizado: recomendado para APIs.
   • Se o aplicativo oferecer suporte ao login interativo no navegador, selecione redirecionamento HTTP 302 Found e depois selecione Microsoft como provedor de redirecionamento.

10. Selecione Adicionar para criar o provedor de identidade.

    A imagem a seguir mostra a configuração exclusiva da Foundry mais estreita.

    

11. Se o app suportar login interativo do navegador, edite o provedor e garanta que a loja de Tokens esteja ativada. Se você criou um novo registro de aplicativo, adicione o ID do aplicativo dele aos aplicativos de cliente permitidos.

Você precisa dos dois IDs de aplicação quando o app suporta login interativo do navegador. Uma API exclusiva para Foundry requer apenas o ID de aplicação da identidade de recurso Foundry pai.

Atualizar o URI do ID de registro do aplicativo

Um URI de ID de aplicação identifica a API protegida como um recurso OAuth. Para uma ferramenta OpenAPI de identidade gerenciada, o público deve corresponder exatamente a um URI de ID de Aplicação registrado no aplicativo Microsoft Entra de autenticação do App Service. O Foundry usa esse valor como público quando solicita um token de acesso com a identidade do recurso pai do Foundry.

O ID da Aplicação e o URI do ID da Aplicação são propriedades diferentes:

• O ID da Aplicação, também chamado de ID do cliente, é um GUID gerado.
• Um URI de ID de aplicação é um URI que identifica uma API ou recurso pertencente à aplicação. Não precisa conter o ID do cliente da aplicação.

Escolha um URI de ID de aplicação estável e trate-o como parte do contrato da API:

O URI deve ser válido, exclusivo no locatário e aceito pela política de URI de ID do Aplicativo do locatário. Uma string simples como some-random-string não é um URI válido de ID de Aplicação.

Este guia utiliza a URL completa do Serviço de Aplicativo HTTPS:

https://<app-name>.azurewebsites.net

1. Depois que a configuração do provedor da Microsoft for concluída, selecione-a na coluna Provedor de identidade para abrir a página de registro do aplicativo.

2. No menu à esquerda, selecione Gerenciar>Expor uma API.

3. Ao lado do URI da ID do Aplicativo, selecione Editar.

4. Altere o valor para a URL HTTPS completa do seu aplicativo do App Service, como https://<app-name>.azurewebsites.net.

   Você pode encontrar o nome do host do aplicativo na página Visão geral no domínio Padrão.

5. Para um novo registro de app, certifique-se de que a versão do token de acesso esteja definida como 2.

6. Clique em Salvar.

Alterar o URI do ID de aplicação posteriormente requer atualizar a audiência da ferramenta Foundry e todos os outros clientes que solicitam tokens para a API.

A configuração correspondente de autenticação da ferramenta OpenAPI é:

{
  "type": "managed_identity",
  "security_scheme": {
    "audience": "https://<app-name>.azurewebsites.net"
  }
}

Você não precisa listar o público da ferramenta em Públicos de token permitidos. A autenticação do App Service reconhece identificadores de recursos que você registra no seu aplicativo Microsoft Entra. Por outro lado, adicionar um valor apenas às audiências de tokens permitidos não registra um recurso OAuth nem permite que a Microsoft Entra emita um token para ele.

Não use o endpoint do projeto Foundry nem a ID do cliente do App Service como público, a menos que você também configure exatamente esse valor como o URI de ID do aplicativo. Outros formatos válidos de URI de ID de aplicação, incluindo api:// URIs, funcionam quando o valor registrado e a audiência coincidem exatamente. Para casos extremos relacionados, veja Perguntas Frequentes.

Configure a API protegida de forma declarativa

Use o Bicep para configurar a API protegida e a política de autenticação do App Service. O padrão a seguir assume o seguinte:

• webApp é o recurso do Serviço de Aplicativos.
• entraAppé um módulo que cria a aplicação de autenticação do Serviço de Aplicativos Microsoft Entra.
• foundryAccountClientId é o ID de aplicação da identidade de recurso do Foundry pai.
• appServiceAuthCredentialSettingName é o nome da configuração do aplicativo que contém o segredo do cliente de autenticação do App Service existente.

No módulo de aplicativo Bicep do Microsoft Graph, configure a URL do App Service como o URI de identificador e solicite tokens de acesso da versão 2:

extension microsoftGraphV1

param environmentName string
param appServiceUrl string

resource app 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'my-app-${environmentName}'
  displayName: 'My app (${environmentName})'
  signInAudience: 'AzureADMyOrg'
  identifierUris: [
    appServiceUrl
  ]
  api: {
    requestedAccessTokenVersion: 2
  }
  web: {
    homePageUrl: appServiceUrl
    redirectUris: [
      '${appServiceUrl}/.auth/login/aad/callback'
    ]
  }
}

output clientId string = app.appId
output webAppUrl string = appServiceUrl

O exemplo a seguir authsettingsV2 permite tanto login interativo do navegador quanto chamadas Foundry OpenAPI:

@description('Parent Foundry resource identity application ID')
param foundryAccountClientId string = ''

resource webAppAuthSettings 'Microsoft.Web/sites/config@2024-11-01' = {
  name: '${webApp.name}/authsettingsV2'
  properties: {
    platform: {
      enabled: true
    }
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'RedirectToLoginPage'
      redirectToProvider: 'azureActiveDirectory'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: entraApp.outputs.clientId
          clientSecretSettingName: appServiceAuthCredentialSettingName
          openIdIssuer: 'https://login.microsoftonline.com/${tenant().tenantId}/v2.0'
        }
        validation: {
          allowedAudiences: [
            'api://${entraApp.outputs.clientId}'
          ]
          defaultAuthorizationPolicy: {
            allowedApplications: concat(
              [
                entraApp.outputs.clientId
              ],
              empty(foundryAccountClientId) ? [] : [foundryAccountClientId]
            )
            allowedPrincipals: {}
          }
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
      }
    }
    httpSettings: {
      requireHttps: true
    }
  }
}

Passe o ID da aplicação da identidade de recurso Foundry através do Azure Developer CLI (AZD):

{
  "foundryAccountClientId": {
    "value": "${AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID=}"
  }
}

Depois, configure o ambiente e reimplante:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Configurar a ferramenta OpenAPI no Microsoft Foundry

1. De volta ao portal do Foundry, selecione seu agente.

2. Localize a ferramenta OpenAPI e selecione ...>Editar.

3. Verifique se a caixa de esquema do OpenAPI 3.0+ contém o esquema do seu app de Serviço de Aplicativos. Se isso não funcionar, cole seu esquema OpenAPI. Para obter mais informações, consulte Como usar o OpenAPI com o Serviço do Foundry Agent.

4. Para o método autenticação, selecione Identidade gerenciada.

5. No campo Audience, insira o URI da ID do aplicativo que você configurou anteriormente. Para a configuração deste guia, use a URL completa em HTTPS do seu app do App Service, como https://<app-name>.azurewebsites.net. Os valores devem coincidir exatamente.

6. Selecione a ferramenta Atualizar.

Testar o agente

1. No portal da Fábrica, selecione seu agente e selecione Experimentar no playground.

2. Fale com o agente para testar seus endpoints OpenAPI. Por exemplo:

   • Mostre-me todas as tarefas.
   • Crie uma tarefa chamada "Comprar mantimentos".
   • Atualize essa tarefa para "Comprar mantimentos e cozinhar o jantar".

Se você configurar a autenticação corretamente, o agente chama as APIs do seu app através da ferramenta OpenAPI.

Perguntas frequentes

Por que posso salvar a ferramenta OpenAPI antes de configurar a autorização do App Service?

Quando você salva uma ferramenta OpenAPI, o Foundry valida seu esquema, formato de audiência e definição. Ele não chama o endpoint do App Service. Portanto, você pode salvar a ferramenta antes de adicionar a identidade do recurso Foundry pai à lista de permissões do App Service.

Configure a lista de permissões antes de invocar a ferramenta no playground ou em tempo de execução. Até lá, o App Service rejeita chamadas de ferramenta.

Por que o público padrão api://<client-id> às vezes falha?

O portal do App Service geralmente cria um aplicativo no Microsoft Entra com api://<application-client-id> como seu URI de ID do aplicativo. Nesse caso, a Foundry pode usar o mesmo valor que seu público.

O provisionamento personalizado ou declarativo pode deixar vazia a coleção identifierUris do aplicativo Microsoft Entra, mesmo quando a autenticação do App Service mostra api://<client-id> em Públicos de token permitidos. Nesse estado, a Foundry não pode obter um token de identidade gerenciada para o valor porque ele não é um identificador de recurso registrado.

Para resolver o problema, use uma destas opções:

• Registre api://<client-id> como o URI de ID do aplicativo e use-o como a audience do Foundry.
• Registre a URL HTTPS do App Service como o URI do ID da aplicação e use essa URL como o público do Foundry.

Não corrija o descompasso adicionando cadeias arbitrárias a allowedAudiences.

A autenticação do App Service pode funcionar sem um URI de ID de Aplicação?

O login interativo do navegador pode funcionar sem um URI de ID de aplicação porque o fluxo do navegador usa um token ID para o ID do cliente da aplicação web.

O fluxo OpenAPI de identidade gerenciada pela Foundry precisa de um token de acesso para um recurso API registrado. Para esse fluxo, configure um URI de ID de aplicação e use o mesmo valor da audiência da ferramenta.

Solucionar problemas de autenticação e autorização

A ferramenta OpenAPI recebe HTTP 401

Uma resposta HTTP 401 significa que a autenticação do App Service não conseguiu autenticar a solicitação. As causas prováveis incluem:

• Você não selecionou identidade gerenciada para a ferramenta OpenAPI.
• O público não corresponde exatamente à URI da ID do aplicativo do Microsoft Entra.
• O emissor ou locatário do token não corresponde ao usado pela autenticação do App Service.
• Você não configurou o URI do ID da aplicação no aplicativo Microsoft Entra.

Verifique se a audiência do OpenAPI corresponde exatamente a um URI de ID do aplicativo registrado. Para a configuração neste guia, o valor é a URL HTTPS completa do App Service.

A ferramenta OpenAPI recebe HTTP 403

Uma resposta HTTP 403 significa que a autenticação foi bem-sucedida, mas as verificações de autorização rejeitaram o chamador. As causas prováveis incluem:

• Você adicionou a identidade do projeto Foundry à lista de permissões em vez da identidade do recurso Foundry pai.
• Você digitou o ID do objeto onde a autenticação do App Service requer um ID de aplicação.
• Você não adicionou o ID da aplicação de recurso pai ao allowedApplications.
• Você não adicionou o ID do objeto de recurso pai à lista de identidades permitidas para uma configuração exclusiva do Foundry.

Inspecione as declarações do token de acesso:

• azp deve ser igual ao ID de aplicação da identidade de recurso do Foundry pai.
• oid deve ser igual ao ID de objeto da identidade do recurso Foundry pai.

Usuários do navegador recebem HTTP 403 após fazer login

Para um aplicativo que suporta login interativo no navegador, verifique estas configurações:

• O ID do cliente do aplicativo web permanece em allowedApplications.
• O requisito de identidade permite usuários normais de locatários.
• Requisições de navegador não autenticadas usam HTTP 302 em vez de HTTP 401.

A ferramenta funciona anonimamente, mas falha após a autenticação ser ativada

Atualize a ferramenta de Anônimo para Identidade Gerenciada, defina o público para um URI registrado de ID de Aplicação e permita a identidade do recurso Foundry pai.

Limpar os recursos

Quando você exclui ou substitui recursos deste cenário:

• Remova a identidade do recurso pai do Foundry da autenticação do App Service ao excluir ou substituir o recurso do Foundry.
• Exclua o aplicativo Microsoft Entra de autenticação do Serviço de Aplicativos quando você excluir permanentemente o aplicativo do Serviço de Aplicativos. Essa etapa também evita o risco, descrito anteriormente, de um URI de ID do aplicativo ficar órfão.
• Se você usar uma identidade atribuída pelo usuário e uma credencial de identidade federada para autenticação sem segredos do Serviço de Aplicativo, exclua essa identidade e essa credencial federada junto com o aplicativo.

Conteúdo relacionado

• Configurar seu app de Serviço de Aplicativo ou Azure Functions para usar as credenciais do Microsoft Entra
• Integrar a IA aos aplicativos do Serviço de Aplicativo do Azure
• O que é o Serviço de Agente da Fábrica?