Compartilhar via

Proteger fluxos de trabalho do agente de conversação com Autenticação Fácil (Autenticação do Serviço de Aplicativo) nos Aplicativos Lógicos do Azure (versão prévia)

Aplica-se a: Aplicativos Lógicos do Azure (Standard)

Importante

Esse recurso está em versão prévia e está sujeito aos Termos de uso suplementares para versões prévias do Microsoft Azure.

Os fluxos de trabalho do agente expandem as opções de integração porque podem trocar mensagens com chamadores mais diversos, como pessoas, agentes, servidores e clientes do PROTOCOLO MCP(Model Context Protocol), agentes de ferramentas e serviços externos. Embora os fluxos de trabalho não-agente interajam com um conjunto de chamadores pequeno, fixo e conhecido, os chamadores de agente podem vir de redes dinâmicas, desconhecidas e não confiáveis. Como resultado, você deve autenticar e impor permissões para cada chamador.

Para ajudar a proteger os fluxos de trabalho do agente de conversação em produção, configure a Autenticação Fácil para autenticar e autorizar chamadores ou pessoas que desejam interagir com seu agente de conversa. A Autenticação Fácil, também conhecida como Autenticação do Serviço de Aplicativo, fornece os seguintes recursos para você usar:

  • Forneça uma identidade validada para cada solicitação de chamador.
  • Atribua conexões a cada usuário.
  • Impor políticas de acesso condicional.
  • Emita credenciais revogadas.
  • Conceda permissões com base em princípios de privilégio mínimo, funções e escopos.
  • Forneça um cliente de chat externo fora do portal do Azure para que as pessoas possam interagir com seu agente de conversa.

Essas medidas permitem que você autentique e autorize cada chamador em um nível refinado e revogue o acesso rapidamente quando necessário. Sem esses controles, você corre o risco de acesso descontrolado, segredos vazados, como URLs de SAS (assinatura de acesso compartilhado) e chaves de acesso, trilhas de auditoria fracas e outros riscos à segurança.

O Easy Auth funciona com a ID do Microsoft Entra como uma camada de segurança separada para fornecer recursos internos de autenticação e autorização que atendam às suas necessidades. Com a imposição de segurança operando fora do fluxo de trabalho, você pode se concentrar mais no desenvolvimento da lógica de negócios. Essa separação de preocupações torna os fluxos de trabalho do agente mais simples e fáceis de criar, depurar, operar, monitorar, manter, governar e auditar.

A segurança de fluxos de trabalho sem agente geralmente envolve SAS estático, segredos rotativos e controles de limite de rede, como restrições de acesso, listas de permissões de IP, rótulos de serviço, integração de rede virtual e pontos de extremidade privados. Com os fluxos de trabalho de agentes, você cria autorização em relação a usuários finais, identidades gerenciadas, entidades de serviço e seus escopos e funções. Essa abordagem permite um alcance global mais seguro, mas ainda permite que ações de fluxo de trabalho downstream respeitem as permissões refinadas.

Este guia mostra como criar um registro de aplicativo e, em seguida, configurar a Autenticação Fácil para seu recurso de aplicativo lógico Standard, que pode conter fluxos de trabalho de agente e nonagent.

Importante

O Easy Auth armazena informações de configuração nas configurações do aplicativo subjacente ao recurso do seu aplicativo lógico, por exemplo, WEBSITE_AUTH_ENABLED, WEBSITE_AUTH_DEFAULT_PROVIDER e MICROSOFT_PROVIDER_AUTHENTICATION_SECRET. Não edite manualmente essas configurações, a menos que você queira configurar a automação usando modelos do ARM, modelos Bicep ou modelos do Terraform.

Para obter mais informações, consulte os seguintes artigos:

Pré-requisitos

Criar o Registro do aplicativo

Para iniciar a configuração do Easy Auth da melhor forma, criar um registro de aplicativo no Microsoft Entra ID diretamente a partir do recurso do seu aplicativo lógico. Se você precisar reutilizar um registro de aplicativo existente, deverá atualizar o registro do aplicativo para trabalhar de forma limpa com clientes do Easy Auth e do Azure.

  1. No portal do Azure, abra o recurso do aplicativo lógico padrão.

  2. No menu da barra lateral do recurso, em Configurações, selecione Autenticação.

  3. Na página Autenticação, selecione Adicionar provedor de identidade.

    A captura de tela mostra o aplicativo lógico Standard com a página Autenticação aberta.

    A página Autenticação agora mostra a guia Noções básicas para configurar o provedor de identidade.

  4. Na guia Noções básicas , para o provedor de identidade, selecione Microsoft para a ID do Microsoft Entra.

  5. Na seção Registro de aplicativo, para o tipo de registro de aplicativo, selecione (Recomendado para agentes de conversação) Crie um novo registro de aplicativo, que mostra as opções correspondentes para essa seleção.

  6. Forneça um nome de exibição exclusivo para o registro do aplicativo, por exemplo: agent-logic-app-reg-prod

  7. Para a identidade gerenciada atribuída pelo usuário, selecione Criar nova identidade gerenciada atribuída pelo usuário.

    Você pode criar uma nova identidade fornecendo um nome ou selecionando uma identidade existente.

  8. Para tipos de conta com suporte, selecione Locatário atual – locatário único , a menos que você queira aceitar intencionalmente outros locatários.

    A configuração de locatário único refere-se apenas a contas no diretório organizacional atual. Portanto, todas as contas de usuário e convidado neste diretório podem usar seu aplicativo ou API. Por exemplo, se o público-alvo for interno à sua organização, use essa configuração.

    O exemplo a seguir mostra a aparência de um registro de aplicativo:

    A captura de tela mostra as informações básicas do registro do aplicativo.

    Importante

    A menos que você tenha políticas explícitas de governança e acesso condicional configuradas, não escolha Nenhum diretório do Microsoft Entra – Multilocatário.

    Para obter mais informações, consulte os seguintes artigos:

  9. Em Verificações adicionais, selecione os seguintes valores se ainda não estiverem selecionados:

    Configurações Value
    Requisito de aplicativo cliente Permitir solicitações somente deste próprio aplicativo
    Requisito de identidade Permitir solicitações de identidades específicas
    Identidades permitidas Aparece somente com Permitir solicitações de identidades específicas selecionado.

    O valor pré-preenchido padrão é a ID do objeto que representa o usuário atual, ou seja, você mesmo. Você pode atualizar esse valor das seguintes maneiras:

    – Incluir IDs de objeto para outros desenvolvedores ou usuários.
    - Use declarações de grupo para incluir um grupo específico, em vez de IDs de objeto individuais.
    - Selecionar um registro de aplicativo existente para o recurso do seu aplicativo lógico. Se você fizer isso, atualize o registro do aplicativo para funcionar de forma limpa com o Easy Auth.

    Para obter mais informações, consulte Usar uma política de autorização interna.
    Requisito de locatário Permitir solicitações somente do inquilino emissor

  10. Ignore a seção Caminhos Excluídos .

  11. Opcionalmente, nas configurações de autenticação do Serviço de Aplicativo, examine as seguintes configurações e execute as ações apropriadas:

    Configurações Ação
    Restringir o acesso A menos que você planeje permitir alguns pontos de extremidade autenticados, selecione Exigir autenticação para bloquear todas as solicitações anônimas.
    Solicitações não autenticadas Com base em o chamador ser ou não um agente, selecione Redirecionamento HTTP 302 Found: recomendado para agentes.

  12. Quando terminar, selecione Adicionar para concluir a adição do provedor de identidade.

    O Azure cria o registro do aplicativo, atualiza as configurações do aplicativo e habilita o runtime do Easy Auth. Quando o Azure concluir, a página Autenticação do aplicativo lógico listará Microsoft como provedor de identidade. Os clientes e os chamadores agora devem autenticar suas identidades. O aplicativo lógico rejeita clientes e chamadores não autenticados, conforme esperado, e emite uma resposta 302 Found redirect ou 401 Unauthorized quando as solicitações não incluem tokens válidos.

    Depois de concluir a criação do registro de aplicativo, mantenha a configuração do Logic App o mais simples possível até confirmar se a autenticação funciona conforme o esperado. Posteriormente, você pode adicionar quaisquer escopos de permissão ou funções de aplicativo que você deseja impor acessando as seguintes páginas no recurso de registro do aplicativo:

    • Na barra lateral do registro do aplicativo, em Gerenciar, selecione Expor uma API para adicionar um escopo de permissão. Para obter mais informações, consulte Adicionar um escopo.

    • Na barra lateral do registro do aplicativo, em Gerenciar, selecione Funções de aplicativo para atribuir uma função de aplicativo. Para obter mais informações, consulte Atribuir função de aplicativo.

    Ou você pode examinar as etapas correspondentes na próxima seção, Atualizar um registro de aplicativo existente.

  13. Para verificar se o registro do aplicativo está configurado corretamente, consulte Testar e validar a configuração de Autenticação Fácil.

Atualizar um registro de aplicativo existente

Se você precisar reutilizar um registro de aplicativo existente que seja compartilhado com outra API ou um protótipo anterior, siga estas etapas para examinar e ajustar as configurações especificadas para que o registro do aplicativo possa funcionar de forma limpa com clientes da Easy Auth e do agente.

  1. Na caixa de pesquisa do portal do Azure, localize e selecione a ID do Microsoft Entra.

  2. No menu da barra lateral, em Gerenciar, selecione Registros de aplicativo e, em seguida, localize e selecione o registro do aplicativo.

  3. No menu da barra lateral de registro de aplicativo, expandir Gerenciar.

  4. Em Gerenciar, selecione Marca & propriedades e confirme se a configuração da URL da Página Inicial especifica a URL do site do logic app.

    Observação

    A URL da home page é opcional para APIs de agentes ou somente back-end. Defina esse valor somente se os usuários finais precisarem de uma página de aterrissagem ou documentação. Os redirecionamentos de token não usam esse valor.

  5. Em Gerenciar, selecione Autenticação.

    1. Nas configurações da Plataforma, verifique se a entrada da Web existe.

    2. Na entrada Web, em URIs de redirecionamento, localizar o URI de retorno de chamada Easy Auth (Autenticação do Serviço de Aplicativo) pré-preenchido, que segue esta sintaxe:

      https://<logic-app-name>.azurewebsites.net/.auth/login/aad/callback

      Mantenha esse valor padrão, a menos que seu cenário precise que você exponha IDs personalizadas do aplicativo de API. Esse URI de retorno de chamada é o token de acessopúblico-alvo padrão e especifica quais recursos podem aceitar tokens de acesso de clientes que desejam acessar esses recursos.

      A finalidade por trás de um público-alvo de token permitido é atender apenas às solicitações que apresentam tokens válidos para esses recursos. Uma solicitação de token de acesso envolve duas partes: o cliente que solicita o token e o recurso que aceita o token. O destinatário é conhecido como o “público-alvo” do token, que, nesse caso, é seu aplicativo lógico.

      Para obter mais informações, consulte o que é um URI de redirecionamento?

    3. Se o Azure não preencher automaticamente a configuração URIs de redirecionamento, insira manualmente o URI com o nome do seu aplicativo lógico, por exemplo:

      https://my-chatbox-logic-app.azurewebsites.net/.auth/login/aad/callback

      Importante

      Não use URIs de redirecionamento personalizadas, a menos que você esteja hospedando um front-end interativo.

    4. Desconsiderar a configuração URL de logout do canal frontal.

    5. Para concessão implícita e fluxos híbridos, selecione ambas as seguintes opções:

      • Tokens de acesso (usados para fluxos implícitos)
      • Tokens de ID (usados para fluxos implícitos e híbridos)

      Para saber mais, confira a seguinte documentação:

    6. Em tipos de conta com suporte, selecione a opção que corresponde às suas necessidades comerciais.

      Na maioria dos casos, escolher Contas neste diretório organizacional apenas (Microsoft somente – Locatário único). Para a opção multilocatário, verifique se você tem políticas explícitas de governança e acesso condicional do Azure configuradas. Para obter mais informações sobre essas opções, consulte diferenças de validação por tipos de conta com suporte.

    7. Em configurações avançadas, para Permitir fluxos de cliente públicos, mantenha a configuração Não para habilitar os fluxos móveis e de área de trabalho especificados.

      A exceção ocorre quando clientes nativos e públicos precisam evitar o fluxo Credenciais de Senha do Proprietário do Recurso (ROPC) usando dispositivo ou código de autenticação.

    8. Quando terminar, selecione Salvar.

  6. Em Gerenciar, selecione Certificados e segredos. Na guia Credenciais Federadas , configure uma nova identidade gerenciada atribuída pelo usuário que tenha acesso ao aplicativo lógico para que você possa usar a identidade gerenciada como uma credencial de identidade federada no registro do aplicativo.

    Se você não tiver uma identidade gerenciada atribuída pelo usuário com acesso ao Logic Apps, siga os seguintes passos:

    1. Criar uma identidade gerenciada atribuída pelo usuário.
    2. Adicione a identidade atribuída pelo usuário ao seu aplicativo lógico.
    3. Configure a identidade atribuída pelo usuário como uma credencial de identidade federada no registro do aplicativo.

  7. Opcionalmente, se você precisar configurar declarações como funções, escopos, grupos de usuários ou XMS_CC, siga estas etapas:

    1. Em Gerenciar, selecione Configuração de Token.

    2. Na seção Declarações opcionais , adicione suas declarações.

      Observação

      Para evitar sobrecarga de token, configure verificações de função ou escopo, em vez de declarações de grupo extensas.

  8. Em Gerenciar, selecione permissões de API e siga estas etapas:

    1. Em Permissões Configuradas, selecione Adicionar uma permissão.
    2. No painel Solicitar permissões de API , na guia APIs da Microsoft , localize e selecione o Microsoft Graph.
    3. Para o tipo de permissões, selecione Permissões delegadas.
    4. Na caixa Selecionar permissões, insiraUser.Read.
    5. Na coluna Permissão , expanda Usuário e selecione a permissão User.Read .

    Para obter mais informações, consulte Adicionar permissões para acessar o Microsoft Graph.

  9. Opcionalmente, em Gerenciar, selecione Expor uma API, para que você possa definir e expor escopos de permissão.

    Na configuração URI de ID do aplicativo, o URI pré-preenchido é um identificador exclusivo que representa o recurso do seu aplicativo lógico como o público-alvo em tokens de acesso e usa o seguinte formato:

    api://<application-client-ID>

    Na seção Escopos definidos por esta API, se quiser depender apenas da validação de funções e público-alvo, não é necessário definir nem expor escopos de permissão. No entanto, se você quiser que os clientes do Azure solicitem permissões delegadas, defina esses escopos seguindo estas etapas:

    1. Selecione Adicionar um escopo e forneça as seguintes informações:

      Configurações Obrigatório Value
      Nome do Escopo Yes user_impersonation
      Quem pode consentir Yes Administradores e usuários
      Nome de exibição de consentimento do administrador Yes Rótulo ou nome do escopo de permissão exibido na mensagem de consentimento quando administradores do locatário dão consentimento para o escopo.

      Por exemplo:
      Acessar <logic-app-name>
      Definição de consentimento do administrador Yes Descrição detalhada do escopo de permissão que aparece quando os administradores de inquilinos expandem o escopo na tela de consentimento.

      Por exemplo:
      Permitir que o aplicativo acesse <logic-app-name> em nome do usuário conectado.
      Nome para exibição do consentimento do usuário Não Nome opcional para o escopo de permissão que a tela de consentimento apresenta quando os usuários finais dão seu consentimento para esse escopo.

      Por exemplo:
      Acessar <logic-app-name>
      Definição de consentimento do usuário Não Descrição detalhada opcional para o escopo de permissão que a tela de consentimento mostra quando os usuários finais expandem o escopo na tela de consentimento.

      Por exemplo:
      Permitir que o aplicativo acesse <logic-app-name> em seu lugar.
      State Yes Habilitado

    2. Quando terminar, selecione Adicionar escopo.

    3. Na lista Escopos , examine as configurações de escopo atualizadas para confirmar se elas aparecem conforme o esperado.

  10. Ao concluir a atualização do registro de aplicativo, ir para o recurso do seu aplicativo lógico Standard.

  11. Na barra lateral do aplicativo lógico, em Configurações, selecione Autenticação.

  12. Na página Autenticação , ao lado das configurações de Autenticação, selecione Editar para examinar as configurações. No painel Editar configurações de autenticação , confirme os seguintes valores:

Configurações Value Description
Autenticação do Serviço de Aplicativo Habilitado Seu aplicativo lógico está configurado e habilitado com a Autenticação Fácil.
Restringir o acesso Exigir autenticação Clientes e chamadores devem autenticar suas identidades.
Solicitações não autenticadas Yes O aplicativo lógico rejeita clientes e chamadores não autenticados, conforme esperado, e emite uma resposta 302 Found redirect ou 401 Unauthorized quando as solicitações não incluem tokens válidos.

Testar e validar a configuração de Autenticação Fácil

Depois de configurar o Easy Auth, a interface de chat interna na página de Chat do fluxo de trabalho no portal do Azure ficará indisponível. Em vez disso, você deve interagir com seu agente de conversa usando o cliente de chat externo que está disponível fora do portal do Azure. Para confirmar se a Autenticação Fácil funciona conforme o esperado, execute seus testes no cliente de chat externo seguindo estas etapas:

  1. Na barra de ferramentas do designer ou na barra lateral do fluxo de trabalho, selecione Chat.

    A interface de chat interna não aparece mais na página Chat .

  2. Na seção Essentials , selecione o link url do cliente de chat , que abre uma nova guia do navegador.

  3. No prompt de solicitação de permissões, forneça seu consentimento e aceite a solicitação.

    A captura de tela mostra o prompt de consentimento da solicitação de permissões.

    A página do navegador é atualizada e mostra a interface do cliente de chat externo.

    Dica

    Você também pode inserir a URL do cliente de chat em um elemento HTML iFrame que você pode usar com seu site em que deseja fornecer o cliente de chat, por exemplo:

    <iframe src="https:/<logic-app-name>.azurewebsites.net/api/agentsChat/<workflow-name>/IFrame" title="<chat-client-name>"></iframe>

  4. Na interface de chat externa, inicie ou continue interagindo com seu agente de conversa.

  5. Para examinar o histórico de execução do fluxo de trabalho, siga estas etapas:

    1. Retorne ao fluxo de trabalho no portal do Azure.

    2. Na barra lateral do fluxo de trabalho, em Ferramentas, selecione Histórico de execuções e, em seguida, selecione a execução mais recente do fluxo de trabalho.

    3. No modo de exibição de monitoramento, confirme se o histórico de execução e os status da operação aparecem conforme o esperado.

Solucionar erros durante o teste de Autenticação Fácil

A tabela a seguir descreve os problemas comuns que você pode encontrar ao configurar a Autenticação Fácil, as possíveis causas e as ações que você pode executar:

Problema ou erro Causa provável Ação
401 com invalid_token + error_description que faz referência ao público Existe uma incompatibilidade entre a audiência destinatária do token de acesso e as audiências permitidas de token especificadas. Verificar se o público-alvo do token de acesso e o público-alvo permitido do token correspondem.
403 Proibido Pode indicar que o fluxo de trabalho ou o agente da solicitação não foi encontrado. Verifique as ações em seu fluxo de trabalho em busca de um problema de autorização.

Usar uma identidade no fluxo de trabalho

Quando a Autenticação Fácil valida uma solicitação, a Autenticação Fácil injeta dados de identidade em cabeçalhos de solicitação com base no provedor de identidade. Seu aplicativo lógico usa esses cabeçalhos para autenticar o chamador.

Para obter mais informações, consulte os seguintes artigos:

Conteúdo relacionado

  • Last updated on