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

När du skapar ett chattprogram med HJÄLP av RAG-mönstret 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.

En behörig användare bör ha åtkomst till svar som finns i chattappens dokument.

En obehörig användare bör inte ha åtkomst till svar från skyddade dokument som de inte har behörighet att se.

Kommentar

Den här artikeln använder en eller flera AI-appmallar som grund för exemplen och vägledningen i artikeln. Med AI-appmallar får du väl underhållna och enkla att distribuera referensimplementeringar som hjälper dig att säkerställa en högkvalitativ startpunkt för dina AI-appar.

Arkitekturöversikt

Utan funktionen 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 viss 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äkerhet- 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 krävs för dokumentsäkerhet i det här exemplet.

Parameter	Syfte
AZURE_USE_AUTHENTICATION	När inställningen är inställd truepå aktiverar du användarinloggning till chattappen och App Service-autentiseringen. Aktiverar Use oid security filter i inställningarna för chattappen Utvecklare.
AZURE_ENFORCE_ACCESS_CONTROL	När värdet är inställt på truekräver autentisering för all dokumentåtkomst. Utvecklarinställningarna för oid- och gruppsäkerhet aktiveras och inaktiveras så att de inte kan inaktiveras från användargränssnittet.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	När inställningen är inställd truepå tillåter den här inställningen autentiserade användare att söka efter dokument som inte har några tilldelade åtkomstkontroller, även när åtkomstkontroll krävs. Den här parametern ska endast användas när AZURE_ENFORCE_ACCESS_CONTROL är aktiverad.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	När inställningen är inställd truepå tillåter den här inställningen oautentiserade användare att använda appen, även när åtkomstkontroll tillämpas. Den här parametern ska endast användas när AZURE_ENFORCE_ACCESS_CONTROL är aktiverad.

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 och 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 och 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:

• En Azure-prenumeration. Skapa en kostnadsfritt
• Azure-kontobehörigheter – Ditt Azure-konto måste ha
  • Behörighet att hantera program i Microsoft Entra-ID.
  • Behörigheter för Microsoft.Authorization/roleAssignments/write, till exempel administratör för användaråtkomst eller ägare.
• Åtkomst beviljad till Azure OpenAI i den önskade Azure-prenumerationen. För närvarande måste man ansöka om att få åtkomst till den här tjänsten. Du kan ansöka om åtkomst till Azure OpenAI genom att fylla i formuläret på https://aka.ms/oai/access.

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

Kodområden (rekommenderas)

• GitHub-konto

Visual Studio Code

• Azure Developer CLI
• Docker Desktop – starta Docker Desktop om det inte redan körs
• Visual Studio Code
• Dev Container-tillägg

Öppna utvecklingsmiljön

Börja nu med en utvecklingsmiljö som har alla beroenden installerade för att slutföra den här artikeln.

GitHub Codespaces (rekommenderas)

GitHub Codespaces kör en utvecklingscontainer som hanteras av GitHub med Visual Studio Code för webben som användargränssnitt. För den enklaste utvecklingsmiljön använder du GitHub Codespaces så att du har rätt utvecklarverktyg och beroenden förinstallerade för att slutföra den här artikeln.

Viktigt!

Alla GitHub-konton kan använda Codespaces i upp till 60 timmar kostnadsfritt varje månad med 2 kärninstanser. Mer information finns i GitHub Codespaces månadsvis inkluderade lagrings- och kärntimmar.

1. Starta processen för att skapa ett nytt GitHub Codespace på grenen main av Azure-Samples/azure-search-openai-demo GitHub-lagringsplatsen.

2. Högerklicka på följande knapp och välj Öppna länk i nya fönster för att ha både utvecklingsmiljön och dokumentationen tillgänglig samtidigt.

   

3. På sidan Skapa kodområde granskar du konfigurationsinställningarna för kodområdet och väljer sedan Skapa nytt kodområde

   

4. Vänta tills kodområdet har startats. Den här startprocessen kan ta några minuter.

5. Logga in på Azure med Azure Developer CLI i terminalen längst ned på skärmen.

   azd auth login
   

6. Slutför autentiseringsprocessen.

7. De återstående uppgifterna i den här artikeln sker i samband med den här utvecklingscontainern.

Visual Studio Code

Dev Containers-tillägget för Visual Studio Code kräver att Docker installeras på den lokala datorn. Tillägget är värd för utvecklingscontainern lokalt med Docker-värden med rätt utvecklarverktyg och beroenden förinstallerade för att slutföra den här artikeln.

1. Skapa en ny lokal katalog på datorn för projektet.

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

2. Öppna Visual Studio Code i den katalogen:

   code .
   

3. Öppna en ny terminal i Visual Studio Code.

4. Kör följande AZD-kommando för att ta GitHub-lagringsplatsen till din lokala dator.

   azd init -t azure-search-openai-demo
   

5. Öppna kommandopaletten, sök efter och välj Dev Containers: Öppna mapp i container för att öppna projektet i en utvecklingscontainer. Vänta tills utvecklingscontainern öppnas innan du fortsätter.

6. Logga in på Azure med Azure Developer CLI.

   azd auth login
   

   Kopiera koden från terminalen och klistra sedan in den i en webbläsare. Följ anvisningarna för att autentisera med ditt Azure-konto.

7. De återstående övningarna i det här projektet sker i samband med den här utvecklingscontainern.

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 din AZURE_TENANT_ID.

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

Om du får ett felmeddelande om klientorganisationens princip för villkorlig åtkomst behöver du en andra klient utan en princip för villkorlig åtkomst.

• Din första klientorganisation, som är associerad med ditt användarkonto, används för AZURE_TENANT_ID miljövariabeln.
• Din andra klientorganisation, utan villkorlig åtkomst, används för AZURE_AUTH_TENANT_ID att miljövariabeln ska få åtkomst till Microsoft Graph. För klienter med en princip för villkorlig åtkomst hittar du ID:t för en andra klient utan en princip för villkorlig åtkomst eller skapar 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 klientorganisationen, som tillåter att användaren loggar in i den värdbaserade programmiljön. Ersätt <YOUR_TENANT_ID> med klientorganisations-ID:t.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Kommentar

Om du har en princip för villkorlig åtkomst i användarklientorganisationen måste du ange en autentiseringsklient.

Distribuera chattapp till Azure

Distributionen omfattar att skapa Azure-resurser, ladda upp dokumenten, skapa Microsoft Entra-identitetsappar (klient och server) och aktivera identitet för värdresursen.

1. Kör följande Azure Developer CLI-kommando för att etablera Azure-resurserna och distribuera källkoden:

   azd up
   

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

   Prompt	Svar
   Miljönamn	Använd ett kort namn med identifierande information, till exempel ditt alias och din app: tjones-secure-chat.
   Prenumeration	Välj en prenumeration för att skapa resurserna i.
   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:en 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 dessa alternativ är markerade och nedtonade (inaktiverade för ändring).

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

8. Välj kortet med What does a product manager do?.

9. Du får ett svar som: The provided sources do not contain specific information about the role of a Product Manager at 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. Dessa krä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 Leta reda på miljökatalogen i mappen i projektets rot och öppna filen med den .env 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 den role_library.pdf bloben i innehållscontainern .

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

   Parameter	Syfte
   --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 chap-appen väljer du Inställningar för utvecklare.
2. I avsnittet ID Token claims (ID-tokenanspråk) kopierar du din objectidentifier. Detta kallas i nästa avsnitt för USER_OBJECT_ID.

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 för role_library.pdf så att du har åtkomst till det.

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

   Parameter	Syfte
   -v	Utförliga utdata.
   --acl-type	Grupp- eller användarobjekt-ID (OID): oids
   --acl-action	Lägg till i ett sökindexfält. Andra alternativ är remove, remove_all, list.
   --åtkomstkontrollista	Grupp eller användares USER_OBJECT_ID
   --URL	Filens plats i Azure Storage, till exempel https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Omge inte URL 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.

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

   Parameter	Syfte
   -v	Utförliga utdata.
   --acl-type	Grupp eller användare (oids): oids
   --acl-action	Lista ett sökindexfält oids. Andra alternativ är remove, remove_all, list.
   --åtkomstkontrollista	Grupp eller användares USER_OBJECT_ID
   --URL	Filens plats i Azure Storage, till exempel https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Omge inte URL 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 din 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 efter din AI Search.

2. Välj sökresursen i listan.

3. Välj Sökhantering –> index.

4. Välj gptkbindex.

5. Välj Visa –> JSON-vy.

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

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

   Detta söker igenom alla dokument där fältet oids har ett 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 din USER_OBJECT_ID har angetts korrekt i Azure AI Search för det 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

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

GitHub Codespaces

Om du tar bort GitHub Codespaces-miljön kan du maximera mängden kostnadsfria timmar per kärna som du får för ditt konto.

Viktigt!

Mer information om ditt GitHub-kontos rättigheter finns i GitHub Codespaces månadsvis inkluderade lagrings- och kärntimmar.

1. Logga in på GitHub Codespaces-instrumentpanelen (https://github.com/codespaces).

2. Leta upp de codespaces som körs från Azure-Samples/azure-search-openai-demo GitHub-lagringsplatsen.

   

3. Öppna snabbmenyn för kodområdet och välj sedan Ta bort.

   

Visual Studio Code

Du behöver inte nödvändigtvis rensa din lokala miljö, men du kan stoppa utvecklingscontainern som körs och återgå till att köra Visual Studio Code i kontexten för en lokal arbetsyta.

1. Öppna kommandopaletten, sök efter Dev Containers-kommandona och välj sedan Dev Containers: Öppna mappen lokalt igen.

   

Dricks

Visual Studio Code stoppar utvecklingscontainern som körs, men containern finns fortfarande i Docker i ett stoppat tillstånd. Du har alltid möjlighet att ta bort containerinstansen, containeravbildningen och volymerna från Docker för att frigöra mer utrymme på den lokala datorn.

Få hjälp

Den här exempellagringsplatsen innehåller felsökningsinformation.

Felsökning

Det här avsnittet innehåller felsökning för problem som är specifika för den här artikeln.

Tillhandahålla autentiseringsklientorganisation

När din autentisering finns i en separat klientorganisation från värdprogrammet måste du ange autentiseringsklientorganisationen med 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	Syfte
   AZURE_AUTH_TENANT_ID	Om AZURE_AUTH_TENANT_ID har angetts är det klientorganisationen som är värd för appen.

2. Distribuera lösningen igen med följande kommando.

   azd up
   

Nästa steg

• Skapa en chattapp med azure OpenAI-metodlösningsarkitektur
• Åtkomstkontroll i Generativa AI-appar med Azure AI Search
• Skapa en Enterprise-redo OpenAI-lösning med Azure API Management
• Utklassning av vektorsökning med hybridhämtnings- och rangordningsfunktioner