Introdução à segurança de documentos de bate-papo para Python

Ao criar um aplicativo de bate-papo usando o padrão RAG com seus próprios dados, certifique-se de que cada usuário receba uma resposta com base em suas permissões. Siga o processo neste artigo para adicionar o controle de acesso a documentos ao seu aplicativo de bate-papo.

Um usuário autorizado deve ter acesso às respostas contidas nos documentos do aplicativo de bate-papo.

Um usuário não autorizado não deve ter acesso a respostas de documentos seguros que ele não tem autorização para ver.

Observação

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

Visão geral da arquitetura

Sem o recurso de segurança de documentos, o aplicativo de bate-papo corporativo tem uma arquitetura simples usando o Azure AI Search e o Azure OpenAI. Uma resposta é determinada a partir de consultas à Pesquisa de IA do Azure onde os documentos são armazenados, em combinação com uma resposta de um modelo 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 bate-papo corporativo:

• Adicione autenticação de cliente ao aplicativo de bate-papo 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 seja acessível a um usuário específico ou por um grupo específico. Dentro do índice de pesquisa, cada documento deve ter um campo filtrável que armazena informações de identidade do usuário ou grupo.

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

• Crie um campo de controle de acesso a documentos 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 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 forem agendadas com um indexador, as alterações serão captadas 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 na Pesquisa de IA do Azure é possível 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 booleano para ativar os recursos necessários para a segurança do documento neste exemplo.

Parâmetro	Finalidade
AZURE_USE_AUTHENTICATION	Quando definido como true, habilita a entrada do usuário no aplicativo de bate-papo e a autenticação do Serviço de Aplicativo. Habilita Use oid security filter nas configurações do desenvolvedor do aplicativo de bate-papo.
AZURE_ENFORCE_ACCESS_CONTROL	Quando definido como true, requer autenticação para qualquer acesso a documentos. As configurações do desenvolvedor para segurança oid e de grupo serã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 só deve ser usado 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 só deve ser usado 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.

Enterprise: Conta necessária + filtro de documentos

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

Variáveis de ambiente:

• AZURE_USE_AUTHENTICATION=verdadeiro
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=verdadeiro
• AZURE_ENFORCE_ACCESS_CONTROL=verdadeiro

Uso misto: conta opcional + filtro de documento

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

Variáveis de ambiente:

• AZURE_USE_AUTHENTICATION=verdadeiro
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=verdadeiro
• AZURE_ENFORCE_ACCESS_CONTROL=verdadeiro
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=verdadeiro

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:

• Assinatura do Azure. Crie um gratuitamente
• Permissões de conta do Azure - Sua Conta do Azure deve ter
  • Permissão para gerenciar aplicativos no Microsoft Entra ID.
  • Permissões Microsoft.Authorization/roleAssignments/write, como Administrador de Acesso de Usuário ou Proprietário.
• Acesso permitido ao OpenAI do Azure na assinatura do Azure desejada. No momento, o acesso a esse serviço é permitido somente por aplicativo. Você pode solicitar acesso ao Serviço OpenAI do Azure preenchendo o formulário em https://aka.ms/oai/access.

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

Codespaces (recomendado)

• Conta do GitHub

Visual Studio Code

• CLI do Desenvolvedor do Azure
• Área de Trabalho do Docker – iniciar o Docker Desktop se ele ainda não estiver em execução
• Visual Studio Code
• Extensão de contêiner de desenvolvimento

Abrir o ambiente de desenvolvimento

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

Codespaces do GitHub (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 Codespaces por até 60 horas gratuitas por mês com 2 instâncias principais. Para saber mais, confira Armazenamento e horas por núcleo incluídos mensalmente no GitHub Codespaces.

1. Inicie o processo para criar um GitHub Codespace no branch main do repositório GitHub 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 no 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 seguinte comando AZD para trazer o repositório do GitHub para o computador local.

   azd init -t azure-search-openai-demo
   

5. Abra a Paleta de Comandos, procure e selecione Contêineres de Desenvolvimento: 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. Entre 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 sua ID de assinatura e ID de locatário com o seguinte comando da CLI do Azure. Copie o valor para usar como seu AZURE_TENANT_IDarquivo .

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

Se você receber um erro sobre a política de acesso condicional do locatário, precisará de um segundo locatário sem uma política de acesso condicional.

• Seu primeiro locatário, associado à sua conta de usuário, é usado para a variável de AZURE_TENANT_ID ambiente.
• Seu segundo locatário, sem acesso condicional, é usado para a variável de ambiente acessar o AZURE_AUTH_TENANT_ID Microsoft Graph. Para locatários com uma política de acesso condicional, localize a ID de um segundo locatário sem 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 o usuário a entrar no ambiente do aplicativo hospedado. Substitua pelo <YOUR_TENANT_ID> ID do locatário.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Observação

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 aplicativo de chat no Azure

A implantação inclui a criação dos recursos do Azure, o carregamento dos documentos, a criação dos aplicativos de identidade do Microsoft Entra (cliente & servidor) e a ativação da identidade para o recurso de hospedagem.

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

   azd up
   

2. Use a tabela a seguir para responder aos prompts de implantação do AZD:

   Prompt	Resposta
   Nome do ambiente	Use um nome curto com informações de identificação, como seu alias e aplicativo: tjones-secure-chat.
   Assinatura	Selecione uma assinatura para criar os recursos.
   Local para recursos do Azure	Selecione uma localização próxima de você.
   Localização para documentIntelligentResourceGroupLocation	Selecione uma localização próxima de você.
   Localização para openAIResourceGroupLocation	Selecione uma localização próxima de 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 tiver sido implantado com êxito, você verá uma URL exibida no terminal.

4. Selecione essa 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 bate-papo for exibido, observe no canto superior direito que o usuário está conectado.

7. Abra as configurações do desenvolvedor e observe que essas duas opções estão selecionadas e acinzentadas (desabilitadas para alteração).

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

8. Selecione o cartão com What does a product manager do?.

9. Você recebe uma resposta como: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

   

Acesso aberto a um documento para um usuário

Ative suas permissões para o documento exato para obter a resposta. Estes requerem 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

Depois que essas informações forem conhecidas, atualize o campo de índice oids de Pesquisa de IA do Azure para o role_library.pdf documento.

Obter o URL de um documento em armazenamento

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

2. Procure a AZURE_STORAGE_ACCOUNT entrada e copie seu valor.

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

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

   Parâmetro	Finalidade
   --account-name	Nome da conta de armazenamento do Microsoft Azure
   --nome-do-contêiner	O nome do contêiner neste exemplo é content
   --name	O nome do blob nesta etapa é role_library.pdf

4. Copie a URL do blob para usar mais tarde.

Obtenha seu ID de usuário

1. No aplicativo chap, selecione Configurações do desenvolvedor.
2. Na seção Declarações de ID Token, copie seu objectidentifierarquivo . Isso é conhecido na próxima seção como o USER_OBJECT_ID.

Fornecer acesso de usuário a um documento na Pesquisa do Azure

1. Use o script a seguir para alterar o oids campo na Pesquisa de IA do Azure 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	Finalidade
   -v	Saída detalhada.
   --tipo ACL	IDs de objeto de grupo ou de usuário (OIDs): oids
   --acl-ação	Adicionar a um campo de índice de pesquisa. Outras opções incluem remove, remove_all, 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 envolva a URL com aspas no comando CLI.

2. A saída do console para esse 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 na Pesquisa de IA do Azure.

   ./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	Finalidade
   -v	Saída detalhada.
   --tipo ACL	Grupo ou usuário (oids): oids
   --acl-ação	Listar um campo oidsde índice de pesquisa . Outras opções incluem remove, remove_all, 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 envolva a URL com aspas no comando CLI.

4. A saída do console para esse 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 seu USER_OBJECT_ID e é usada para determinar se o documento é usado na resposta com o Azure OpenAI.

Verifique se a Pesquisa de IA do Azure contém seus USER_OBJECT_ID

1. Abra o portal do Azure e procure o seu AI Searcharquivo .

2. Selecione seu recurso de pesquisa na lista.

3. Selecione Gerenciamento de pesquisa -> Índices.

4. Selecione o gptkbindex.

5. Selecione Exibir -> modo de exibição JSON.

6. Substitua o JSON pelo seguinte JSON.

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

   Isso pesquisa todos os documentos onde o oids campo tem qualquer valor e retorna os sourcefilecampos , e oids .

7. Se o role_library.pdf não tiver seu oid, retorne à seção Fornecer acesso de usuário a um documento na Pesquisa do Azure 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 USER_OBJECT_ID está definido corretamente na Pesquisa de IA do Azure para isso role_library.pdf.

1. Retorne ao aplicativo de bate-papo. Talvez seja necessário entrar novamente.

2. Insira a mesma consulta para que o role_library conteúdo 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 os recursos

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 do Azure Developer CLI para excluir os recursos do Azure e remover o código-fonte:

azd down --purge

Limpar GitHub Codespaces

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 (https://github.com/codespaces).

2. Localize seus Codespaces atualmente em execução, originados do repositório Azure-Samples/azure-search-openai-demo do GitHub.

   

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

   

Visual Studio Code

Você não precisa necessariamente limpar seu ambiente local, mas pode interromper o contêiner de desenvolvimento em execução e retornar à execução do Visual Studio Code no contexto de um espaço de trabalho local.

1. Abra a Paleta de Comandos, procure os comandos Contêineres de Desenvolvimento e selecione Contêineres de Desenvolvimento: Reabrir Pasta Localmente.

   

Dica

O Visual Studio Code interromperá o contêiner de desenvolvimento em execução, mas o contêiner ainda existirá no Docker em um estado interrompido. 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.

Solução de problemas

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

Fornecer locatário de autenticação

Quando sua autenticação está em um locatário separado do seu aplicativo de hospedagem, você precisa definir esse locatário de autenticação com o processo a seguir.

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	Finalidade
   AZURE_AUTH_TENANT_ID	Se AZURE_AUTH_TENANT_ID estiver definido, é o locatário que hospeda o aplicativo.

2. Reimplante a solução com o comando a seguir.

   azd up
   

Próximas etapas

• Criar um aplicativo de chat com a arquitetura de solução de práticas recomendadas do Azure OpenAI
• Controle de acesso em aplicativos de IA generativos com a Pesquisa de IA do Azure
• Criar uma solução OpenAI pronta para empresas com o Gerenciamento de API do Azure
• Superando a busca em vetores com recursos de recuperação e classificação híbridas