Kom igång med chattdokumentsäkerhet för Python

När du skapar ett chattprogram med hjälp av RAG-mönstret (Retrieval Augmented Generation) med dina egna data kontrollerar du att varje användare får ett svar baserat på deras behörigheter. Följ processen i den här artikeln för att lägga till dokumentåtkomstkontroll i chattappen.

• Behörig användare: Den här personen ska ha åtkomst till svar som finns i chattappens dokument.

  

• Obehörig användare: Den här personen ska inte ha åtkomst till svar från skyddade dokument som de inte har behörighet att se.

  

Översikt över arkitektur

Utan en funktion för dokumentsäkerhet har företagschattappen en enkel arkitektur med hjälp av Azure AI Search och Azure OpenAI. Ett svar bestäms från frågor till Azure AI Search där dokumenten lagras, i kombination med ett svar från en Azure OpenAI GPT-modell. Ingen användarautentisering används i det här enkla flödet.

Om du vill lägga till säkerhet för dokumenten måste du uppdatera företagschattappen:

• Lägg till klientautentisering i chattappen med Microsoft Entra.
• Lägg till logik på serversidan för att fylla i ett sökindex med användar- och gruppåtkomst.

Azure AI Search ger inte inbyggda behörigheter på dokumentnivå och kan inte variera sökresultat från ett index efter användarbehörigheter. I stället kan ditt program använda sökfilter för att säkerställa att ett dokument är tillgängligt för en specifik användare eller en specifik grupp. I ditt sökindex bör varje dokument ha ett filterbart fält som lagrar information om användar- eller gruppidentitet.

Eftersom auktoriseringen inte finns internt i Azure AI Search måste du lägga till ett fält för att lagra användar- eller gruppinformation och sedan filtrera dokument som inte matchar. För att implementera den här tekniken måste du:

• Skapa ett dokumentåtkomstkontrollfält i ditt index som är dedikerat för att lagra information om användare eller grupper med dokumentåtkomst.
• Fyll i dokumentets åtkomstkontrollfält med relevant användar- eller gruppinformation.
• Uppdatera det här åtkomstkontrollfältet när det finns ändringar i behörigheter för användar- eller gruppåtkomst.

Om dina indexuppdateringar schemaläggs med en indexerare hämtas ändringarna vid nästa indexeringskörning. Om du inte använder en indexerare måste du indexera om manuellt.

I den här artikeln möjliggörs processen för att skydda dokument i Azure AI Search med exempelskript som du som sökadministratör skulle köra. Skripten associerar ett enskilt dokument med en enskild användaridentitet. Du kan använda dessa skript och tillämpa dina egna säkerhets- och produktionskrav för att skala efter dina behov.

Fastställa säkerhetskonfiguration

Lösningen innehåller booleska miljövariabler för att aktivera funktioner som är nödvändiga för dokumentsäkerhet i det här exemplet.

Använd följande avsnitt för att förstå de säkerhetsprofiler som stöds i det här exemplet. Den här artikeln konfigurerar Företagsprofilen.

Företag: Obligatoriskt konto + dokumentfilter

Varje användare av webbplatsen måste logga in. Webbplatsen innehåller innehåll som är offentligt för alla användare. Säkerhetsfiltret på dokumentnivå tillämpas på alla begäranden.

Miljövariabler:

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

Blandad användning: Valfritt konto + dokumentfilter

Varje användare av webbplatsen kan logga in. Webbplatsen innehåller innehåll som är offentligt för alla användare. Säkerhetsfiltret på dokumentnivå tillämpas på alla begäranden.

Miljövariabler:

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

Förutsättningar

En utvecklingscontainermiljö är tillgänglig med alla beroenden som krävs för att slutföra den här artikeln. Du kan köra utvecklingscontainern i GitHub Codespaces (i en webbläsare) eller lokalt med hjälp av Visual Studio Code.

Om du vill använda den här artikeln behöver du följande krav:

• Ett Azure-abonnemang. Skapa en kostnadsfritt.
• Azure-kontobehörigheter: Ditt Azure-konto måste ha:
  • Behörighet att hantera program i Microsoft Entra-ID.
  • Microsoft.Authorization/roleAssignments/write behörigheter, till exempel administratör för användaråtkomst eller ägare.

Du behöver fler förutsättningar beroende på vilken utvecklingsmiljö du föredrar.

Öppna en utvecklingsmiljö

Använd följande instruktioner för att distribuera en förkonfigurerad utvecklingsmiljö som innehåller alla nödvändiga beroenden för att slutföra den här artikeln.

Hämta nödvändig information med Azure CLI

Hämta ditt prenumerations-ID och klient-ID med följande Azure CLI-kommando. Kopiera värdet som ska användas som ditt AZURE_TENANT_ID värde.

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

Om du får ett felmeddelande om din klientorganisations princip för villkorlig åtkomst, behöver du en annan klient utan principen för villkorlig åtkomst.

• Din första klientorganisation, som är associerad med ditt användarkonto, används som miljövariabel för AZURE_TENANT_ID.
• Din andra tenant, utan villkorlig åtkomst, används för att miljövariabeln AZURE_AUTH_TENANT_ID ska få åtkomst till Microsoft Graph. För klienter med en princip för villkorlig åtkomst, hitta ID:t för en andra klientorganisation utan en princip för villkorlig åtkomst eller skapa en ny klientorganisation.

Ange miljövariabler

1. Kör följande kommandon för att konfigurera programmet för Företagsprofilen .

   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. Kör följande kommando för att ange instansen, som auktoriserar användarens inloggning till värdmiljön för applikationer. Ersätt <YOUR_TENANT_ID> med klientorganisations-ID:t.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Distribuera chattappen till Azure

Distributionen består av följande steg:

• Skapa Azure-resurserna.
• Ladda upp dokumenten.
• Skapa Microsoft Entra-identitetsappar (klient och server).
• Aktivera identiteten för värdresursen.

1. Etablera Azure-resurserna och distribuera källkoden.

   azd up
   

2. Använd följande tabell för att besvara AZD distributionsprompterna.

   Omedelbar	Svar
   Miljönamn	Använd ett kort namn med identifierande information, till exempel ditt alias och din app. Och exempel är tjones-secure-chat.
   Prenumeration	Välj en prenumeration där resurserna ska skapas.
   Plats för Azure-resurser	Välj en plats nära dig.
   Plats för documentIntelligentResourceGroupLocation	Välj en plats nära dig.
   Plats för openAIResourceGroupLocation	Välj en plats nära dig.

   Vänta 5 eller 10 minuter efter att appen har distribuerats så att appen kan startas.

3. När programmet har distribuerats visas en URL i terminalen.

4. Välj den URL som är märkt (✓) Done: Deploying service webapp för att öppna chattprogrammet i en webbläsare.

   

5. Godkänn popup-fönstret för appautentisering.

6. När chattappen visas ser du i det övre högra hörnet att användaren är inloggad.

7. Öppna inställningar för utvecklare och observera att båda följande alternativ är markerade och inaktiverade för ändring:

   • Använda oid-säkerhetsfilter
   • Använda säkerhetsfilter för grupper

8. Välj kortet med Vad gör en produktansvarig?.

9. Du får ett svar som: De angivna källorna innehåller inte specifik information om rollen som produktchef på Contoso Electronics.

   

Öppna åtkomst till ett dokument för en användare

Aktivera dina behörigheter för det exakta dokumentet så att du kan få svaret. Du behöver flera informationsdelar:

• Azure Storage
  • Kontonamn
  • Containerns namn
  • Blob-/dokument-URL för role_library.pdf
• Användarens ID i Microsoft Entra-ID

När den här informationen är känd uppdaterar du indexfältet för Azure AI Search oids för role_library.pdf dokumentet.

Hämta URL:en för ett dokument i lagring

1. .azure Hitta miljökatalogen vid roten av projektet och öppna .env-filen i den katalogen.

2. Sök efter posten AZURE_STORAGE_ACCOUNT och kopiera dess värde.

3. Använd följande Azure CLI-kommandon för att hämta URL:en för bloben role_library.pdf i containern content .

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

   Parameter	Avsikt
   --account-name	Azure Storage-kontonamn.
   --container-name	Containernamnet i det här exemplet är content.
   --Namn	Blobnamnet i det här steget är role_library.pdf.

4. Kopiera blob-URL:en så att den används senare.

Hämta ditt användar-ID

1. I chattappen väljer du Inställningar för utvecklare.
2. I avsnittet ID-tokenanspråk kopierar du parametern objectidentifier . Den här parametern kallas i nästa avsnitt USER_OBJECT_IDför .

Ge användaren åtkomst till ett dokument i Azure Search

1. Använd följande skript för att ändra fältet oids i Azure AI Search till role_library.pdf så att du får åtkomst till det.

   python ./scripts/manageacl.py --acl-type oids --acl-action add --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parameter	Avsikt
   -v	Utförliga utdata.
   --acl-type	Grupp- eller användar-OID:er: oids.
   --acl-action	Lägg till i ett sökindexfält. Andra alternativ är enable_acls, remove, remove_alloch view.
   --acl	Grupp eller användare USER_OBJECT_ID.
   --URL	Filens plats i Azure Storage, till exempel https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Omge inte URL:en med citattecken i CLI-kommandot.

2. Konsolutdata för det här kommandot ser ut så här:

   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. Du kan också använda följande kommando för att kontrollera att din behörighet visas för filen i Azure AI Search.

   python ./scripts/manageacl.py -v --acl-type groups --acl-action view --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parameter	Avsikt
   -v	Utförliga utdata.
   --acl-type	Grupp- eller användar-OID:er: oids.
   --acl-action	Visa ett sökindexfält oids. Andra alternativ är enable_acls, remove, remove_alloch add.
   --URL	Filens plats som visas, till exempel https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Omge inte URL:en med citattecken i CLI-kommandot.

4. Konsolutdata för det här kommandot ser ut så här:

   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]
   

   Matrisen i slutet av utdata innehåller parametern USER_OBJECT_ID och används för att avgöra om dokumentet används i svaret med Azure OpenAI.

Kontrollera att Azure AI Search innehåller dina USER_OBJECT_ID

1. Öppna Azure-portalen och sök AI Searchefter .

2. Välj sökresursen i listan.

3. Välj Sökhanteringsindex>.

4. Välj gptkbindex.

5. Välj Visa>.

6. Ersätt JSON med följande JSON:

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

   Den här JSON-filen söker igenom alla dokument där fältet oids har valfritt värde och returnerar fälten sourcefile och oids .

7. role_library.pdf Om du inte har din OID går du tillbaka till avsnittet Ge användaren åtkomst till ett dokument i Azure Search och slutför stegen.

Verifiera användaråtkomst till dokumentet

Om du har slutfört stegen men inte ser rätt svar kontrollerar du att parametern USER_OBJECT_ID är korrekt inställd i Azure AI Search för role_library.pdf.

1. Gå tillbaka till chattappen. Du kan behöva logga in igen.

2. Ange samma fråga så att role_library innehållet används i Azure OpenAI-svaret: What does a product manager do?.

3. Visa resultatet, som nu innehåller lämpligt svar från rollbiblioteksdokumentet.

   

Rensa resurser

Följande steg beskriver hur du rensar de resurser du använde.

Rensa Azure-resurser

De Azure-resurser som skapas i den här artikeln faktureras till din Azure-prenumeration. Om du inte förväntar dig att behöva dessa resurser i framtiden tar du bort dem för att undvika att debiteras mer.

Kör följande Azure Developer CLI-kommando för att ta bort Azure-resurserna och ta bort källkoden.

azd down --purge

Rensa GitHub Codespaces och Visual Studio Code

Följande steg beskriver hur du rensar de resurser du använde.

Få hjälp

Exempellagringsplatsen innehåller felsökningsinformation.

Felsökning

Det här avsnittet hjälper dig att felsöka problem som är specifika för den här artikeln.

Ange autentiseringstenant

När din autentisering finns i en separat tenant från värdprogrammet måste du ställa in denna autentiseringstjänst enligt följande process.

1. Kör följande kommando för att konfigurera exemplet så att det använder en andra klient för autentiseringsklientorganisationen.

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

   Parameter	Avsikt
   AZURE_AUTH_TENANT_ID	Om AZURE_AUTH_TENANT_ID har angetts är det klientorganisationen som är värd för appen.

2. Distribuera om lösningen med följande kommando:

   azd up
   

Relaterat innehåll

• Skapa en chattapp med Azure OpenAI bästa praxis för lösningsarkitektur.
• Lär dig mer om åtkomstkontroll i generativa AI-appar med Azure AI Search.
• Skapa en företagsklar Azure OpenAI-lösning med Azure API Management.
• Se Azure AI Search: Överträffar vektorsökning med hybridåterhämtnings- och rankningsfunktioner.