Introdução à segurança de documentos de chat 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 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 utilizador não autorizado não deve ter acesso a respostas de documentos seguros que não tenha autorização para ver.

Descrição geral da arquitetura

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

O Azure AI Search 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 seu índice de pesquisa, cada documento deve ter um campo filtrável que armazena 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 quaisquer documentos que não correspondam. 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 este 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 no Azure AI Search é 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.

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

Empresa: Conta obrigatória + filtro de documentos

Cada usuário do site deve entrar, e o site contém conteúdo que é 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=verdadeiro
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=verdadeiro
• AZURE_ENFORCE_ACCESS_CONTROL=verdadeiro

Uso misto: Conta opcional + filtro de documentos

Cada utilizador do site pode iniciar sessão, e o site contém conteúdo que é público para todos os utilizadores. O filtro de segurança no nível do 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 no GitHub Codespaces (em um navegador) ou localmente usando o Visual Studio Code.

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

• Subscrição do Azure. Crie um gratuitamente
• Permissões da conta do Azure - Sua conta do Azure deve ter
  • Permissão para gerenciar aplicativos no Microsoft Entra ID.
  • Microsoft.Authorization/roleAssignments/write permissions, como Administrador de Acesso de Usuário ou Proprietário.
• Acesso concedido ao Azure OpenAI na subscrição pretendida do Azure. Atualmente, o acesso a este serviço é concedido apenas por pedido. Você pode solicitar acesso ao Azure OpenAI preenchendo o formulário em https://aka.ms/oai/access.

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

Ambiente de desenvolvimento aberto

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

Obtenha as 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 AZURE_TENANT_ID variável de 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 seguintes comandos 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 seguinte comando para definir o locatário, que autoriza o usuário a entrar no ambiente do aplicativo hospedado. Substitua <YOUR_TENANT_ID> pelo ID do locatário.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Implantar o 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 da CLI do Desenvolvedor do Azure 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:

   Pedido	Resposta
   Nome do ambiente	Use um nome curto com informações de identificação, como seu alias e aplicativo: tjones-secure-chat.
   Subscrição	Selecione uma assinatura para criar os recursos.
   Localização dos recursos do Azure	Selecione uma localização próxima de si.
   Localização para documentIntelligentResourceGroupLocation	Selecione uma localização próxima de si.
   Localização para openAIResourceGroupLocation	Selecione uma localização próxima de si.

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

3. Depois que o aplicativo for implantado com êxito, você verá uma URL exibida no terminal.

4. Selecione esse URL rotulado (✓) Done: Deploying service webapp para abrir o aplicativo de bate-papo 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 seu usuário está conectado.

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

   • Use o 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 utilizador

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 contentor
  • URL do 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 do Azure AI Search para o role_library.pdf documento.

Obter o URL de um documento armazenado

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

2. Procure a entrada e copie o AZURE_STORAGE_ACCOUNT 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	Propósito
   --nome-da-conta	Nome da conta de Armazenamento do Microsoft Azure
   --nome do recipiente	O nome do recipiente neste exemplo é content
   --nome	O nome do blob nesta etapa é role_library.pdf

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

Obtenha o seu ID de utilizador

1. No aplicativo chap, selecione Configurações do desenvolvedor.
2. Na seção Declarações de token de ID, copie o arquivo objectidentifier. 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	Propósito
   -v	Saída detalhada.
   --tipo ACL	IDs de objeto de grupo ou usuário (OIDs): oids
   --acl-ação	Adicionar a um campo Índice de pesquisa. Outras opções incluem remove, remove_all, list.
   --LCA	Grupo ou utilizador 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 URL com aspas no comando CLI.

2. A saída do console para este comando se parece com:

   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.
   --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.
   --LCA	Grupo ou utilizador 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 URL com aspas no comando CLI.

4. A saída do console para este comando se parece com:

   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 o Azure AI Search contém seus USER_OBJECT_ID

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

2. Selecione seu recurso de pesquisa na lista.

3. Selecione Gerenciamento de pesquisa -> Índices.

4. Selecione o gptkbindex.

5. Selecione View -> JSON view.

6. Substitua o JSON pelo seguinte JSON.

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

   Isso pesquisa todos os documentos em que o oids campo tem algum 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 sua USER_OBJECT_ID está definida corretamente no Azure AI Search para isso role_library.pdf.

1. Volte ao aplicativo de bate-papo. Poderá ter de iniciar sessão 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.

   

Clean up resources (Limpar recursos)

Limpar recursos do Azure

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

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 espaços de código do GitHub

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 específicos deste artigo.

Fornecer locatário de autenticação

Quando sua autenticação estiver em um locatário separado do seu aplicativo de hospedagem, você precisará definir esse locatário 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, é o locatário que hospeda o aplicativo.

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

   azd up
   

Próximos passos

• Crie um aplicativo de bate-papo com a arquitetura de solução de práticas recomendadas do Azure OpenAI
• Controle de acesso em aplicativos de IA generativa com a Pesquisa de IA do Azure
• Crie uma solução OpenAI pronta para empresas com o Azure API Management
• Superando a pesquisa vetorial com recursos híbridos de recuperação e classificação