Autenticar numa Azure Function App usando "Easy Auth" (Pesquisa de IA do Azure)

Este artigo explica como configurar uma ligação indexadora a uma aplicação Azure Function usando as capacidades de autenticação integradas do Serviço de Aplicações do Azure, também conhecido como "Easy Auth". As aplicações Azure Function são uma excelente solução para alojar APIs Web Personalizadas que um serviço Pesquisa de IA do Azure pode usar para enriquecer o conteúdo ingerido durante uma execução de indexador ou, se estiver a usar um modelo de embedding personalizado para vetorização integrada, vetorizar conteúdo numa consulta de pesquisa.

Pode usar uma identidade gerida atribuída pelo sistema ou pelo utilizador do serviço de pesquisa para autenticar contra a aplicação Azure Function. Esta abordagem requer a configuração de um registo de aplicação Microsoft Entra ID para usar como fornecedor de autenticação para a aplicação Azure Function, o que é explicado neste artigo.

Pré-requisitos

• Uma identidade gerida para o seu serviço de pesquisa.

Configure a aplicação Microsoft Entra ID como fornecedor de autenticação

Para usar o Microsoft Entra ID como um provedor de autenticação para o aplicativo Azure Function, um registro de aplicativo deve ser criado. Existem duas opções: criar uma automaticamente através da própria aplicação Azure Function ou usar uma aplicação existente. Para saber mais sobre estes passos, consulte a documentação do App Service.

Independentemente da opção, certifique-se de que o registo da aplicação está configurado de acordo com os seguintes passos para garantir que é compatível com o Pesquisa de IA do Azure.

Verifique se o registo da aplicação tem o URI da ID de aplicação configurado

O registo de aplicação deve ser configurado com um URI de ID de aplicação, que pode ser usado como audiência de token com aplicações Azure Functions e Pesquisa de IA do Azure. Configure-o no formato api://<applicationId>. Isso pode ser feito navegando até à secção de Visão Geral do registo da aplicação e definindo o campo URI da ID de Aplicação.

Definir tipos de conta suportados para autenticação

Vá à secção de Autenticação do registo da aplicação e configure os tipos de conta suportados para que apenas as contas no mesmo diretório organizacional do registo da aplicação possam usá-lo para autenticação.

(Opcional) Configurar um segredo do cliente

O App Service recomenda a utilização de um segredo de cliente para a aplicação do provedor de autenticação. A autenticação ainda funciona sem segredo do cliente, desde que as permissões delegadas estejam configuradas. Para configurar um segredo do cliente, navegue até a seção Certificados & segredos do registro do aplicativo e adicione um Novo segredo do cliente, conforme explicado neste artigo.

Adicionar um escopo para delegar permissões

Navegue até a seção Expor uma API e configure o registro do aplicativo para ter um escopo que delegue permissões de administrador e usuário a ele, para garantir que ele seja compatível com o fluxo de autenticação do indexador.

Depois que o escopo de permissões delegadas estiver configurado, você deverá observar na seção de permissões da API do registro do aplicativo que a API User.Read no Microsoft.Graph está definida.

Configurar o fornecedor de autenticação do Microsoft Entra ID na aplicação Azure Function

Com a aplicação cliente registada com as especificações anteriores, a autenticação Microsoft Entra ID para a aplicação Azure Function pode ser configurada seguindo a documentação do App Service. Navegue até a seção Autenticação do aplicativo Azure Function para configurar os detalhes de autenticação.

Verifique se as configurações a seguir estão definidas para garantir que o Pesquisa de IA do Azure possa se autenticar com êxito no aplicativo Azure Function.

Configurar definições de autenticação

• Verifique se a autenticação do Serviço de Aplicativo está habilitada
• Restringir o acesso ao aplicativo Azure Function para Exigir autenticação
• Para solicitações não autenticadas, prefira HTTP 401: Não autorizado

A captura de tela a seguir destaca essas configurações específicas para um aplicativo de exemplo do Azure Function.

Adicionar provedor de autenticação do Microsoft Entra ID

• Adicione o Microsoft Entra ID como o provedor de autenticação para o aplicativo Azure Function.
• Crie um novo registro de aplicativo ou escolha um registro de aplicativo configurado anteriormente. Certifique-se de que está configurado de acordo com as diretrizes na seção anterior deste documento.
• Verifique se na seção Audiências de token permitidas , o URI da ID do aplicativo do registro do aplicativo está especificado. Deve estar no formato api://<applicationId>, correspondendo ao que foi configurado com o registo da aplicação criado anteriormente.
• Se desejar, pode configurar outras verificações para restringir o acesso especificamente ao indexador.

Configurar outras verificações

• Certifique-se de que a ID do Objeto (principal) da identidade específica do serviço Pesquisa de IA do Azure esteja especificada como o requisito de Identidade, marcando a opção Permitir solicitações de identidades específicas e inserindo a ID do Objeto (principal) na seção de identidade.

• No requisito da aplicação cliente, selecione a opção Permitir pedidos de uma aplicação cliente específica. Você precisa procurar a ID de Cliente para a identidade do serviço Pesquisa de IA do Azure. Para fazer isso, copie a ID de objeto (principal) da etapa anterior e pesquise no seu tenant do Microsoft Entra ID. Deve haver uma aplicação empresarial correspondente cuja página de visão geral lista um ID da aplicação, que é o GUID que precisa ser especificado como requisito da aplicação cliente.

• Para o requisito de locatário, escolha qualquer uma das opções que se alinhe com sua postura de segurança. Para mais informações, consulte a documentação do App Service.

Configurar uma ligação à aplicação Azure Function

Dependendo se a conexão com o aplicativo Azure Function precisa ser feita em uma habilidade de API Web Personalizada ou em um vetorizador de API Web Personalizada, a definição JSON é ligeiramente diferente. Em ambos os casos, certifique-se de especificar o URI correto para o Azure Function app e defina o authResourceId como sendo o mesmo valor que a audiência de tokens permitida configurada para o provedor de autenticação.

Dependendo se escolhe ligar usando uma identidade atribuída pelo sistema ou pelo utilizador, as propriedades necessárias diferem ligeiramente.

Usar uma identidade atribuída ao sistema

Eis um exemplo de como chamar uma função denominada test para a aplicação Azure Function de exemplo, em que a identidade atribuída pelo sistema ao serviço de pesquisa tem permissão para se autenticar através do "Easy Auth".

"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000"

Usar uma identidade atribuída pelo usuário

Eis um exemplo para invocar a mesma função, em que a identidade específica atribuída ao utilizador pode autenticar-se através do "Easy Auth". É necessário especificar o ID de recurso da identidade exata atribuída pelo utilizador a utilizar na propriedade identity da configuração.

"uri": "https://contoso-function-app.azurewebsites.net/api/test?",
"authResourceId": "api://00000000-0000-0000-0000-000000000000",
"identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }

Execute o indexador/vetorizador para verificar as permissões

Para habilidades de API Web personalizada, as permissões são validadas durante o tempo de execução do indexador. No caso do vetorizador, são validados quando é efetuada uma consulta vetorial com o vetorizador Custom Web API. Para excluir quaisquer problemas específicos com a autenticação, você pode testar desativando o provedor de autenticação no aplicativo Azure Function e garantindo que as chamadas do indexador/vetorizador sejam bem-sucedidas.

• Se os problemas de autenticação persistirem, certifique-se de que as informações de identidade corretas - ou seja, ID do aplicativo, ID do objeto (principal) para a identidade do serviço Pesquisa de IA do Azure sejam especificadas no provedor de autenticação do aplicativo Azure Function.

Conteúdo relacionado

• Habilidade de API Web personalizada
• Vetorizador de API Web personalizado