Introdução à segurança do documento de chat para Python

Ao criar um aplicativo de chat usando o padrão rag (geração aumentada de recuperação) com seus próprios dados, verifique se cada usuário recebe uma resposta com base em suas permissões. Siga o processo neste artigo para adicionar o controle de acesso de documentos ao seu aplicativo de chat.

• Usuário autorizado: Esta pessoa deve ter acesso às respostas contidas nos documentos do aplicativo de chat.

  

• Usuário não autorizado: pessoa que não deve ter acesso a respostas de documentos protegidos que não tem autorização para ver.

  

Nota

Este artigo usa um ou mais modelos de aplicativo de IA como base para os exemplos e diretrizes no artigo. Os modelos de aplicativo de IA fornecem implementações de referência bem mantidas que são fáceis de implantar. Eles ajudam a garantir um ponto de partida de alta qualidade para seus aplicativos de IA.

Visão geral da arquitetura

Sem um recurso de segurança de documento, o aplicativo de chat empresarial tem uma arquitetura simples usando o Azure AI Search e o Azure OpenAI. Uma resposta é determinada a partir de consultas para o Azure AI Search em que os documentos são armazenados, em combinação com uma resposta de um modelo de GPT do Azure OpenAI. Nenhuma autenticação de usuário é usada nesse fluxo simples.

Para adicionar segurança aos documentos, você precisa atualizar o aplicativo de chat empresarial:

• Adicione a autenticação do cliente ao aplicativo de chat com o Microsoft Entra.
• Adicione lógica do lado do servidor para preencher um índice de pesquisa com acesso de usuário e grupo.

A Pesquisa de IA do Azure não fornece permissões nativas no nível do documento e não pode variar os resultados da pesquisa de dentro de um índice por permissões de usuário. Em vez disso, seu aplicativo pode usar filtros de pesquisa para garantir que um documento esteja acessível a um usuário específico ou por um grupo específico. No índice de pesquisa, cada documento deve ter um campo filtrado que armazene informações de identidade de usuário ou grupo.

Como a autorização não está contida nativamente no Azure AI Search, você precisa adicionar um campo para armazenar informações de usuário ou grupo e, em seguida, filtrar documentos que não correspondem. Para implementar essa técnica, você precisa:

• Crie um campo de controle de acesso de documento em seu índice dedicado a armazenar os detalhes de usuários ou grupos com acesso a documentos.
• Preencha o campo de controle de acesso do documento com os detalhes relevantes do usuário ou do grupo.
• Atualize esse campo de controle de acesso sempre que houver alterações nas permissões de acesso de usuário ou grupo.

Se as atualizações de índice estiverem agendadas com um indexador, as alterações serão detectadas na próxima execução do indexador. Se você não usar um indexador, precisará reindexar manualmente.

Neste artigo, o processo de proteção de documentos no Azure AI Search é viabilizado com scripts de exemplo , que você, como administrador de pesquisa, executaria. Os scripts associam um único documento a uma única identidade de usuário. Você pode usar esses scripts e aplicar seus próprios requisitos de segurança e produção para dimensionar de acordo com suas necessidades.

Determinar a configuração de segurança

A solução fornece variáveis de ambiente boolianas para ativar os recursos necessários para a segurança do documento neste exemplo.

Parâmetro	Propósito
AZURE_USE_AUTHENTICATION	Quando definido como true, permite que o usuário entre no aplicativo de chat e na autenticação do Serviço de Aplicativo do Azure. Habilita Use oid security filter nas configurações do Desenvolvedor do aplicativo de chat .
AZURE_ENFORCE_ACCESS_CONTROL	Quando definido como true, requer autenticação para qualquer acesso a documentos. As configurações do desenvolvedor para ID de objeto (OID) e segurança de grupo são ativadas e desabilitadas para que não possam ser desabilitadas da interface do usuário.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Quando definida como true, essa configuração permite que usuários autenticados pesquisem em documentos que não têm controles de acesso atribuídos, mesmo quando o controle de acesso é necessário. Esse parâmetro deve ser usado somente quando AZURE_ENFORCE_ACCESS_CONTROL estiver habilitado.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Quando definida como true, essa configuração permite que usuários não autenticados usem o aplicativo, mesmo quando o controle de acesso é imposto. Esse parâmetro deve ser usado somente quando AZURE_ENFORCE_ACCESS_CONTROL estiver habilitado.

Use as seções a seguir para entender os perfis de segurança com suporte neste exemplo. Este artigo configura o perfil Enterprise .

Empresa: conta necessária + filtro de documento

Cada usuário do site deve fazer login. O site contém conteúdo público para todos os usuários. O filtro de segurança no nível do documento é aplicado a todas as solicitações.

Variáveis de ambiente:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Uso misto: conta opcional + filtro de documento

Cada usuário do site pode entrar. O site contém conteúdo público para todos os usuários. O filtro de segurança no nível do documento é aplicado a todas as solicitações.

Variáveis de ambiente:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Pré-requisitos

Um ambiente de contêiner de desenvolvimento está disponível com todas as dependências necessárias para concluir este artigo. Você pode executar o contêiner de desenvolvimento em Codespaces do GitHub (em um navegador) ou localmente usando o Visual Studio Code.

Para usar este artigo, você precisa dos seguintes pré-requisitos:

• Uma assinatura do Azure. Crie um gratuitamente.
• Permissões de conta do Azure: sua conta do Azure deve ter:
  • Permissão para gerenciar aplicativos na ID do Microsoft Entra.
  • Permissões Microsoft.Authorization/roleAssignments/write, como Administrador de Acesso do Usuário ou Proprietário.

Você precisa de mais pré-requisitos dependendo do seu ambiente de desenvolvimento preferido.

GitHub Codespaces (recomendado)

• conta do GitHub

Visual Studio Code

• CLI do Desenvolvedor do Azure.
• Docker Desktop. Inicie o Docker Desktop se ele ainda não estiver em execução.
• Visual Studio Code.
• Extensão de contêineres de desenvolvimento.

Abrir um ambiente de desenvolvimento

Comece agora com um ambiente de desenvolvimento que tenha todas as dependências instaladas para concluir este artigo.

GitHub Codespaces (recomendado)

O GitHub Codespaces executa um contêiner de desenvolvimento gerenciado pelo GitHub com o Visual Studio Code para Web como interface do usuário. Para o ambiente de desenvolvimento mais simples, use os Codespaces do GitHub para que você tenha as ferramentas e dependências de desenvolvedor corretas pré-instaladas para concluir este artigo.

Importante

Todas as contas do GitHub podem usar GitHub Codespaces por até 60 horas gratuitas por mês com duas instâncias principais. Para mais informações, veja Armazenamento e horas por núcleo incluídos mensalmente no GitHub Codespaces.

1. Inicie o processo para criar um novo codespace do GitHub no branch main do repositório GitHub do Azure-Samples/azure-search-openai-demo.

2. Clique com o botão direito do mouse no botão a seguir e selecione Abrir link em novas janelas para ter o ambiente de desenvolvimento e a documentação disponíveis ao mesmo tempo.

   

3. Na página Criar codespace, analise as definições de configuração do codespace e selecione Criar novo codespace.

   

4. Aguarde até que o codespace seja iniciado. Esse processo de inicialização pode levar alguns minutos.

5. No terminal na parte inferior da tela, entre no Azure com o Azure Developer CLI.

   azd auth login
   

6. Conclua o processo de autenticação.

7. As tarefas restantes neste artigo ocorrem no contexto desse contêiner de desenvolvimento.

Visual Studio Code

A extensão Dev Containers para Visual Studio Code requer que o Docker seja instalado no computador local. A extensão hospeda o contêiner de desenvolvimento localmente usando o host do Docker com as ferramentas e dependências de desenvolvedor corretas pré-instaladas para concluir este artigo.

1. Crie um novo diretório local em seu computador para o projeto.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Abra o Visual Studio Code nesse diretório.

   code .
   

3. Abra um novo terminal no Visual Studio Code.

4. Execute o comando AZD a seguir para trazer o repositório GitHub para o computador local.

   azd init -t azure-search-openai-demo
   

5. Abra a paleta de Comando e pesquise e selecione Dev Containers: Abrir Pasta no Contêiner para abrir o projeto em um contêiner de desenvolvimento. Aguarde até que o contêiner de desenvolvimento seja aberto antes de continuar.

6. Faça login no Azure com o Azure Developer CLI.

   azd auth login
   

   Copie o código do terminal e cole-o em um navegador. Siga as instruções para autenticar com sua conta do Azure.

7. Os exercícios restantes neste projeto ocorrem no contexto desse contêiner de desenvolvimento.

Obter informações necessárias com a CLI do Azure

Obtenha a ID da assinatura e a ID do locatário com o seguinte comando da CLI do Azure. Copie o valor a ser usado como seu valor de AZURE_TENANT_ID.

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

Se você receber um erro relacionado à política de acesso condicional do seu locatário, precisará de um segundo locatário que não tenha essa política.

• Seu primeiro locatário, associado à sua conta de usuário, é usado para a variável de ambiente AZURE_TENANT_ID.
• Seu segundo locatário, sem acesso condicional, é usado para acessar o Microsoft Graph através da variável de ambiente AZURE_AUTH_TENANT_ID. Para locatários com uma política de acesso condicional, localize o ID de um segundo locatário que não tenha uma política de acesso condicional ou crie um novo locatário.

Definir variáveis de ambiente

1. Execute os comandos a seguir para configurar o aplicativo para o perfil Enterprise.

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Execute o comando a seguir para definir o locatário, que autoriza a entrada do usuário no ambiente do aplicativo hospedado. Substitua <YOUR_TENANT_ID> pela ID do locatário.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nota

Se você tiver uma política de acesso condicional em seu locatário de usuário, precisará especificar um locatário de autenticação.

Implantar o aplicativo de chat no Azure

A implantação consiste nas seguintes etapas:

• Crie os recursos do Azure.
• Carregue os documentos.
• Crie os aplicativos de identidade do Microsoft Entra (cliente e servidor).
• Ative a identidade do recurso de hospedagem.

1. Execute o seguinte comando da CLI do Desenvolvedor do Azure para provisionar os recursos do Azure e implantar o código-fonte.

   azd up
   

2. Use a seguinte tabela para responder aos prompts de desenvolvimento AZD.

   Rápido	Resposta
   Nome do ambiente	Use um nome curto com informações de identificação, como seu alias e aplicativo. E o exemplo é tjones-secure-chat.
   Subscrição	Selecione uma assinatura na qual criar os recursos.
   Local para recursos do Azure	Selecione um local próximo a você.
   Local para documentIntelligentResourceGroupLocation	Selecione um local próximo a você.
   Local para openAIResourceGroupLocation	Selecione um local próximo a você.

   Aguarde 5 ou 10 minutos após a implantação do aplicativo para permitir que o aplicativo seja iniciado.

3. Depois que o aplicativo é implantado com êxito, uma URL é exibida no terminal.

4. Selecione a URL rotulada (✓) Done: Deploying service webapp para abrir o aplicativo de chat em um navegador.

   

5. Concorde com o pop-up de autenticação do aplicativo.

6. Quando o aplicativo de chat for exibido, observe no canto superior direito que o usuário está conectado.

7. Abra Configurações do Desenvolvedor e observe que ambas as seguintes opções estão selecionadas e desabilitadas para alteração:

   • Usar o filtro de segurança oid
   • Usar filtro de segurança de grupos

8. Selecione o cartão com O que um gerente de produto faz?.

9. Você obtém uma resposta como: As fontes fornecidas não contêm informações específicas sobre a função de um Gerente de Produto na Contoso Electronics.

   

Abrir o acesso a um documento para um usuário

Ative suas permissões para o documento exato para que você possa obter a resposta. Você precisa de várias informações:

• Armazenamento do Azure
  • Nome da conta
  • Nome do contêiner
  • URL de blob/documento para role_library.pdf
• ID do usuário no Microsoft Entra ID

Quando essas informações forem conhecidas, atualize o campo oids de índice do Azure AI Search para o documento role_library.pdf.

Obter a URL de um documento no armazenamento

1. Na pasta .azure na raiz do projeto, localize o diretório do ambiente e abra o arquivo .env com esse diretório.

2. Pesquise a entrada AZURE_STORAGE_ACCOUNT e copie seu valor.

3. Use os seguintes comandos da CLI do Azure para obter a URL do blob de role_library.pdf no contêiner content.

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Parâmetro	Propósito
   --account-name	Nome da conta do Armazenamento do Azure.
   --container-name	O nome do contêiner neste exemplo é content.
   --nome	O nome do blob nesta etapa é role_library.pdf.

4. Copie a URL do blob para usar posteriormente.

Obter sua ID de usuário

1. No aplicativo de chat, selecione Configurações do desenvolvedor.
2. Na seção de declarações do Token de ID, copie o parâmetro objectidentifier. Esse parâmetro é conhecido na próxima seção como USER_OBJECT_ID.

Fornecer acesso do usuário a um documento no Azure Search

1. Use o script a seguir para alterar o campo oids no Azure AI Search para role_library.pdf para que você tenha acesso a ele.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action add \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parâmetro	Propósito
   -v	Saída detalhada.
   --acl-type	OIDs de grupo ou de usuário: oids.
   --acl-action	Adicionar a um campo de índice de pesquisa. Outras opções incluem remove, remove_alle list.
   --acl	Grupo ou usuário USER_OBJECT_ID.
   --url	O local do arquivo no Armazenamento do Azure, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Não coloque a URL entre aspas na linha de comando.

2. A saída do console para este comando tem a seguinte aparência:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. Opcionalmente, use o comando a seguir para verificar se sua permissão está listada para o arquivo no Azure AI Search.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parâmetro	Propósito
   -v	Saída detalhada.
   --acl-type	OIDs de grupo ou de usuário: oids.
   --acl-action	Listar um campo de índice de pesquisa oids. Outras opções incluem remove, remove_alle list.
   --acl	Parâmetro USER_OBJECT_ID do grupo ou usuário.
   --url	A localização do arquivo que é mostrada, como https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Não coloque a URL entre aspas na linha de comando (CLI).

4. A saída do console para este comando tem a seguinte aparência:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   A matriz no final da saída inclui o parâmetro USER_OBJECT_ID e é usada para determinar se o documento é usado na resposta com o Azure OpenAI.

Verifique se a Pesquisa Azure AI contém seu USER_OBJECT_ID

1. Abra o portal do Azure e pesquise por AI Search.

2. Selecione o recurso de pesquisa na lista.

3. Selecione Gerenciamento de pesquisa>Índices.

4. Selecione gptkbindex.

5. Selecione Exibir>visualização JSON.

6. Substitua o JSON pelo seguinte JSON:

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   Este JSON pesquisa todos os documentos em que o campo oids tem qualquer valor e retorna os campos sourcefile e oids.

7. Se o role_library.pdf não tiver sua OID, retorne ao Forneça acesso do usuário a um documento na seção do Azure Search e conclua as etapas.

Verificar o acesso do usuário ao documento

Se você concluiu as etapas, mas não viu a resposta correta, verifique se o parâmetro USER_OBJECT_ID está definido corretamente no Azure AI Search para role_library.pdf.

1. Retorne ao aplicativo de chat. Talvez seja necessário entrar novamente.

2. Insira a mesma consulta para que o conteúdo do role_library seja usado na resposta do Azure OpenAI: What does a product manager do?.

3. Exiba o resultado, que agora inclui a resposta apropriada do documento da biblioteca de funções.

   

Limpar recursos

As etapas a seguir explicam o processo de limpeza dos recursos usados.

Limpar recursos do Azure

Os recursos do Azure criados neste artigo são cobrados para sua assinatura do Azure. Se você não espera precisar desses recursos no futuro, exclua-os para evitar incorrer em mais encargos.

Execute o seguinte comando da CLI do Desenvolvedor do Azure para excluir os recursos do Azure e remover o código-fonte.

azd down --purge

Limpar os codespaces do GitHub e o Visual Studio Code

As etapas a seguir explicam o processo de limpeza dos recursos usados.

Codespaces do GitHub

A exclusão do ambiente GitHub Codespaces garante que você possa maximizar a quantidade de horas gratuitas por núcleo que você tem direito na sua conta.

Importante

Para saber mais sobre os direitos da sua conta do GitHub, confira O GitHub Codespaces inclui mensalmente armazenamento e horas de núcleo.

1. Entre no painel do GitHub Codespaces.

2. Localize seus codespaces em execução que são originados no repositório do GitHub Azure-Samples/azure-search-openai-demo.

   

3. Abra o menu de contexto do codespace e selecione Excluir.

   

Visual Studio Code

Você não é necessariamente obrigado a limpar seu ambiente local, mas pode parar o contêiner de desenvolvimento em execução e voltar a executar o Visual Studio Code no contexto de um workspace local.

1. Abra a paleta Comando e pesquise pelos comandos Contêineres de desenvolvimento.

2. Selecione Contêineres de desenvolvimento: reabrir pasta localmente.

   

Dica

O Visual Studio Code interrompe o contêiner de desenvolvimento em execução, mas o contêiner ainda existe no Docker em um estado parado. Você sempre tem a opção de excluir a instância de contêiner, a imagem de contêiner e os volumes do Docker para liberar mais espaço no computador local.

Obter ajuda

Este repositório de exemplo oferece informações de solução de problemas.

Resolução de problemas

Esta seção oferece solução de problemas para problemas específicos deste artigo.

Fornecer locatário de autenticação

Quando a autenticação está em um tenant separado do aplicativo de hospedagem, você precisará definir esse tenant de autenticação com o seguinte processo.

1. Execute o comando a seguir para configurar o exemplo para usar um segundo locatário para o locatário de autenticação.

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Parâmetro	Propósito
   AZURE_AUTH_TENANT_ID	Se AZURE_AUTH_TENANT_ID estiver definido, será o locatário que hospeda o aplicativo.

2. Reimplante a solução com o seguinte comando:

   azd up
   

Conteúdo relacionado

• Crie um aplicativo de chat com a arquitetura de solução de melhores práticas do Azure OpenAI.
• Veja o controle de acesso em aplicativos da IA Generativa com a Pesquisa de IA do Azure.
• Crie uma solução OpenAI pronta para empresas com o Gerenciamento de API do Azure.
• Consulte Azure AI Search: Superando a busca vetorial com recursos híbridos de recuperação e classificação.