Delen via

Aan de slag met beveiliging van chatdocument voor Python

  • Artikel

Wanneer u een chattoepassing bouwt met behulp van het RAG-patroon met uw eigen gegevens, moet u ervoor zorgen dat elke gebruiker een antwoord ontvangt op basis van hun machtigingen. Volg het proces in dit artikel om documenttoegangsbeheer toe te voegen aan uw chat-app.

Een geautoriseerde gebruiker moet toegang hebben tot antwoorden in de documenten van de chat-app.

Schermopname van de chat-app met antwoord met vereiste verificatietoegang.

Een niet-geautoriseerde gebruiker mag geen toegang hebben tot antwoorden van beveiligde documenten die ze niet mogen zien.

Schermopname van de chat-app met antwoord dat aangeeft dat de gebruiker geen toegang heeft tot gegevens.

Notitie

In dit artikel worden een of meer AI-app-sjablonen gebruikt als basis voor de voorbeelden en richtlijnen in het artikel. AI-app-sjablonen bieden u een goed onderhouden, eenvoudig te implementeren referentie-implementaties die u helpen een startpunt van hoge kwaliteit voor uw AI-apps te garanderen.

Architectuuroverzicht

Zonder documentbeveiligingsfunctie heeft de bedrijfschat-app een eenvoudige architectuur met behulp van Azure AI Search en Azure OpenAI. Een antwoord wordt bepaald van query's naar Azure AI Search waar de documenten worden opgeslagen, in combinatie met een antwoord van een Azure OpenAI GPT-model. Er wordt geen gebruikersverificatie gebruikt in deze eenvoudige stroom.

Architectuurdiagram met een antwoord dat is bepaald van query's naar Azure AI Search waar de documenten worden opgeslagen, in combinatie met een promptantwoord van Azure OpenAI.

Als u beveiliging voor de documenten wilt toevoegen, moet u de enterprise-chat-app bijwerken:

  • Voeg clientverificatie toe aan de chat-app met Microsoft Entra.
  • Voeg logica aan de serverzijde toe om een zoekindex te vullen met gebruikers- en groepstoegang.

Architectuurdiagram met een gebruiksverificatie met Microsoft Entra-id en geeft die verificatie vervolgens door aan Azure AI Search.

Azure AI Search biedt geen systeemeigen machtigingen op documentniveau en kan de zoekresultaten niet variëren van binnen een index op gebruikersmachtigingen. In plaats daarvan kan uw toepassing zoekfilters gebruiken om ervoor te zorgen dat een document toegankelijk is voor een specifieke gebruiker of voor een specifieke groep. Binnen de zoekindex moet elk document een filterbaar veld hebben waarin gebruikers- of groepsidentiteitsgegevens worden opgeslagen.

Architectuurdiagram dat laat zien dat voor het beveiligen van de documenten in Azure AI Search elk document gebruikersverificatie bevat, die wordt geretourneerd in de resultatenset.

Omdat de autorisatie niet standaard is opgenomen in Azure AI Search, moet u een veld toevoegen om gebruikers- of groepsgegevens op te slaan en vervolgens documenten filteren die niet overeenkomen. Als u deze techniek wilt implementeren, moet u het volgende doen:

  • Maak een veld voor documenttoegangsbeheer in uw index dat is toegewezen aan het opslaan van de details van gebruikers of groepen met documenttoegang.
  • Vul het toegangsbeheerveld van het document in met de relevante gebruikers- of groepsdetails.
  • Werk dit toegangsbeheerveld bij wanneer er wijzigingen zijn in toegangsmachtigingen voor gebruikers of groepen.
  • Als uw indexupdates zijn gepland met een indexeerfunctie, worden wijzigingen opgehaald bij de volgende uitvoering van de indexeerfunctie. Als u geen indexeerfunctie gebruikt, moet u handmatig opnieuw indexeren.

In dit artikel wordt het proces voor het beveiligen van documenten in Azure AI Search mogelijk gemaakt met voorbeeldscripts , die u als zoekbeheerder zou uitvoeren. De scripts koppelen één document aan één gebruikersidentiteit. U kunt deze scripts gebruiken en uw eigen beveiligings- en productievereisten toepassen om naar uw behoeften te schalen.

Beveiligingsconfiguratie bepalen

De oplossing biedt booleaanse omgevingsvariabelen om functies in te schakelen die nodig zijn voor documentbeveiliging in dit voorbeeld.

Parameter Doel
AZURE_USE_AUTHENTICATION Wanneer deze optie is ingesteld true, schakelt u gebruikersaanmelding in bij de chat-app en App Service-verificatie. Use oid security filter Hiermee schakelt u de instellingen voor ontwikkelaars van de chat-app in.
AZURE_ENFORCE_ACCESS_CONTROL Als dit is ingesteld trueop, is verificatie vereist voor toegang tot documenten. De instellingen voor ontwikkelaars voor oid- en groepsbeveiliging worden ingeschakeld en uitgeschakeld, zodat ze niet kunnen worden uitgeschakeld vanuit de gebruikersinterface.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS Wanneer deze instelling is ingesteld true, kunnen geverifieerde gebruikers zoeken in documenten waaraan geen toegangsbeheer is toegewezen, zelfs wanneer toegangsbeheer is vereist. Deze parameter mag alleen worden gebruikt wanneer AZURE_ENFORCE_ACCESS_CONTROL deze is ingeschakeld.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS Wanneer deze instelling is ingesteld true, kunnen niet-geverifieerde gebruikers de app gebruiken, zelfs wanneer toegangsbeheer wordt afgedwongen. Deze parameter mag alleen worden gebruikt wanneer AZURE_ENFORCE_ACCESS_CONTROL deze is ingeschakeld.

Gebruik de volgende secties om inzicht te krijgen in de beveiligingsprofielen die in dit voorbeeld worden ondersteund. In dit artikel wordt het Enterprise-profiel geconfigureerd.

Onderneming: Vereist account + documentfilter

Elke gebruiker van de site moet zich aanmelden en de site bevat wel inhoud die openbaar is voor alle gebruikers. Het beveiligingsfilter op documentniveau wordt toegepast op alle aanvragen.

Omgevingsvariabelen:

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

Gemengd gebruik: Optioneel account + documentfilter

Elke gebruiker van de site kan zich aanmelden en de site bevat wel inhoud die openbaar is voor alle gebruikers. Het beveiligingsfilter op documentniveau wordt toegepast op alle aanvragen.

Omgevingsvariabelen:

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

Vereisten

Er is een ontwikkelcontaineromgeving beschikbaar met alle afhankelijkheden die nodig zijn om dit artikel te voltooien. U kunt de ontwikkelcontainer uitvoeren in GitHub Codespaces (in een browser) of lokaal met behulp van Visual Studio Code.

Als u dit artikel wilt gebruiken, hebt u de volgende vereisten nodig:

U hebt meer vereisten nodig, afhankelijk van uw favoriete ontwikkelomgeving.

Open ontwikkelomgeving

Begin nu met een ontwikkelomgeving waarop alle afhankelijkheden zijn geïnstalleerd om dit artikel te voltooien.

GitHub Codespaces voert een ontwikkelcontainer uit die wordt beheerd door GitHub met Visual Studio Code voor het web als de gebruikersinterface. Voor de eenvoudigste ontwikkelomgeving gebruikt u GitHub Codespaces zodat u de juiste ontwikkelhulpprogramma's en afhankelijkheden vooraf hebt geïnstalleerd om dit artikel te voltooien.

Belangrijk

Alle GitHub-accounts kunnen Codespaces elke maand maximaal 60 uur gratis gebruiken met 2 kernexemplaren. Zie GitHub Codespaces maandelijks inbegrepen opslag- en kernuren voor meer informatie.

  1. Start het proces om een nieuwe GitHub Codespace te maken op de main vertakking van de Azure-Samples/azure-search-openai-demo GitHub-opslagplaats.

  2. Klik met de rechtermuisknop op de volgende knop en selecteer De koppeling Openen in nieuwe vensters om zowel de ontwikkelomgeving als de documentatie tegelijkertijd beschikbaar te maken.

    Openen in GitHub Codespaces

  3. Controleer op de pagina Codespace maken de configuratie-instellingen voor codespace en selecteer vervolgens Nieuwe codespace maken

    Schermopname van het bevestigingsscherm voordat u een nieuwe coderuimte maakt.

  4. Wacht tot de coderuimte is gestart. Dit opstartproces kan enkele minuten duren.

  5. Meld u in de terminal onderaan het scherm aan bij Azure met de Azure Developer CLI.

    azd auth login

  6. Voltooi het verificatieproces.

  7. De resterende taken in dit artikel vinden plaats in de context van deze ontwikkelingscontainer.

Vereiste informatie ophalen met Azure CLI

Haal uw abonnements-id en tenant-id op met de volgende Azure CLI-opdracht. Kopieer de waarde die u wilt gebruiken als uw AZURE_TENANT_ID.

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

Als u een foutmelding krijgt over het beleid voor voorwaardelijke toegang van uw tenant, hebt u een tweede tenant nodig zonder beleid voor voorwaardelijke toegang.

  • Uw eerste tenant, gekoppeld aan uw gebruikersaccount, wordt gebruikt voor de AZURE_TENANT_ID omgevingsvariabele.
  • Uw tweede tenant, zonder voorwaardelijke toegang, wordt gebruikt voor de AZURE_AUTH_TENANT_ID omgevingsvariabele voor toegang tot Microsoft Graph. Voor tenants met beleid voor voorwaardelijke toegang zoekt u de id van een tweede tenant zonder beleid voor voorwaardelijke toegang of maakt u een nieuwe tenant.

Omgevingsvariabelen instellen

  1. Voer de volgende opdrachten uit om de toepassing voor het Enterprise-profiel te configureren.

    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. Voer de volgende opdracht uit om de tenant in te stellen, waarmee de gebruiker zich kan aanmelden bij de gehoste toepassingsomgeving. Vervang door <YOUR_TENANT_ID> de tenant-id.

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>

Notitie

Als u een beleid voor voorwaardelijke toegang hebt voor uw gebruikerstenant, moet u een verificatietenant opgeven.

Chat-app implementeren in Azure

Implementatie omvat het maken van de Azure-resources, het uploaden van de documenten, het maken van de Microsoft Entra-identiteits-apps (client en server) en het inschakelen van identiteit voor de hostingresource.

  1. Voer de volgende Azure Developer CLI-opdracht uit om de Azure-resources in te richten en de broncode te implementeren:

    azd up

  2. Gebruik de volgende tabel om de AZD-implementatieprompts te beantwoorden:

    Prompt Antwoord
    Omgevingsnaam Gebruik een korte naam met het identificeren van gegevens zoals uw alias en app: tjones-secure-chat.
    Abonnement Selecteer een abonnement waarin u de resources wilt maken.
    Locatie voor Azure-resources Selecteer een locatie bij u in de buurt.
    Locatie voor documentIntelligentResourceGroupLocation Selecteer een locatie bij u in de buurt.
    Locatie voor openAIResourceGroupLocation Selecteer een locatie bij u in de buurt.

    Wacht 5 of 10 minuten nadat de app is geïmplementeerd, zodat de app kan worden opgestart.

  3. Nadat de toepassing is geïmplementeerd, ziet u een URL die wordt weergegeven in de terminal.

  4. Selecteer die URL die is gelabeld (✓) Done: Deploying service webapp om de chattoepassing in een browser te openen.

    Schermopname van de chat-app in de browser met verschillende suggesties voor chatinvoer en het tekstvak voor chat om een vraag in te voeren.

  5. Ga akkoord met het pop-upvenster voor app-verificatie.

  6. Wanneer de chat-app wordt weergegeven, ziet u in de rechterbovenhoek dat uw gebruiker is aangemeld.

  7. Open Instellingen voor ontwikkelaars en u ziet dat deze opties zijn geselecteerd en grijs worden weergegeven (uitgeschakeld voor wijziging).

    • Oid-beveiligingsfilter gebruiken
    • Beveiligingsfilter voor groepen gebruiken

  8. Selecteer de kaart met What does a product manager do?.

  9. U krijgt een antwoord zoals: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

    Schermopname van de chat-app in de browser waarin het antwoord niet kan worden geretourneerd

Toegang tot een document voor een gebruiker openen

Schakel uw machtigingen voor het exacte document in, zodat u het antwoord kunt krijgen. Hiervoor zijn verschillende stukjes informatie vereist:

  • Azure Storage
    • Accountnaam
    • Containernaam
    • Blob/document-URL voor role_library.pdf
  • Gebruikers-id in Microsoft Entra-id

Zodra deze informatie bekend is, werkt u het indexveld oids van Azure AI Search voor het role_library.pdf document bij.

De URL voor een document in opslag ophalen

  1. Zoek in de .azure map in de hoofdmap van het project de omgevingsmap en open het .env bestand met die map.

  2. Zoek de AZURE_STORAGE_ACCOUNT vermelding en kopieer de waarde.

  3. Gebruik de volgende Azure CLI-opdrachten om de URL van de role_library.pdf blob op te halen in de inhoudscontainer .

    az storage blob url \
    --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
    --container-name 'content' \
    --name 'role_library.pdf'
    Parameter Doel
    --accountnaam Naam van Azure Storage-account
    --containernaam De containernaam in dit voorbeeld is content
    --naam De blobnaam in deze stap is role_library.pdf

  4. Kopieer de blob-URL om later te gebruiken.

Uw gebruikers-id ophalen

  1. Selecteer instellingen voor ontwikkelaars in de chap-app.
  2. Kopieer uw objectidentifierid-tokenclaimsectie in de sectie Id-tokenclaims. Dit staat bekend in de volgende sectie als de USER_OBJECT_ID.

  1. Gebruik het volgende script om het oids veld in Azure AI Search te wijzigen voor role_library.pdf zodat u er toegang toe hebt.

    ./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action add \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    Parameter Doel
    -v Uitgebreide uitvoer.
    --acl-type Groeps- of gebruikersobject-id's (OID's): oids
    --acl-action Toevoegen aan een zoekindexveld. Andere opties zijn remove, remove_all, list.
    --Acl Groeperen of gebruikers USER_OBJECT_ID
    --URL De locatie van het bestand in Azure Storage, zoals https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Plaats geen URL tussen aanhalingstekens in de CLI-opdracht.

  2. De console-uitvoer voor deze opdracht ziet er als volgt uit:

    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. Gebruik desgewenst de volgende opdracht om te controleren of uw machtiging wordt vermeld voor het bestand in 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 Doel
    -v Uitgebreide uitvoer.
    --acl-type Groep of gebruiker (oids): oids
    --acl-action Een zoekindexveld weergeven oids. Andere opties zijn remove, remove_all, list.
    --Acl Groeperen of gebruikers USER_OBJECT_ID
    --URL De locatie van het bestand in Azure Storage, zoals https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Plaats geen URL tussen aanhalingstekens in de CLI-opdracht.

  4. De console-uitvoer voor deze opdracht ziet er als volgt uit:

    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]

    De matrix aan het einde van de uitvoer bevat uw USER_OBJECT_ID en wordt gebruikt om te bepalen of het document wordt gebruikt in het antwoord met Azure OpenAI.

Controleer of Azure AI Search uw USER_OBJECT_ID bevat

  1. Open Azure Portal en zoek uw AI Search.

  2. Selecteer uw zoekresource in de lijst.

  3. Selecteer Zoekbeheer -> Indexen.

  4. Selecteer de gptkbindex.

  5. Selecteer Weergave -> JSON-weergave.

  6. Vervang de JSON door de volgende JSON.

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

    Hiermee worden alle documenten doorzocht waar het oids veld een waarde heeft en worden de sourcefileen oids velden geretourneerd.

  7. Als de role_library.pdf oid niet over uw oid beschikt, gaat u terug naar de sectie Gebruikerstoegang bieden tot een document in Azure Search en voert u de stappen uit.

Gebruikerstoegang tot het document controleren

Als u de stappen hebt voltooid, maar het juiste antwoord niet hebt gezien, controleert u of uw USER_OBJECT_ID juist is ingesteld in Azure AI Search.role_library.pdf

  1. Ga terug naar de chat-app. Mogelijk moet u zich opnieuw aanmelden.

  2. Voer dezelfde query in zodat de role_library inhoud wordt gebruikt in het Azure OpenAI-antwoord: What does a product manager do?.

  3. Bekijk het resultaat, dat nu het juiste antwoord uit het document van de rolbibliotheek bevat.

    Schermopname van de chat-app in de browser waarin het antwoord wordt geretourneerd.

Resources opschonen

Azure-resources opschonen

De Azure-resources die in dit artikel zijn gemaakt, worden gefactureerd voor uw Azure-abonnement. Als u deze resources in de toekomst niet meer nodig hebt, verwijdert u deze om te voorkomen dat er meer kosten in rekening worden gebracht.

Voer de volgende Azure Developer CLI-opdracht uit om de Azure-resources te verwijderen en de broncode te verwijderen:

azd down --purge

GitHub Codespaces opschonen

Als u de GitHub Codespaces-omgeving verwijdert, zorgt u ervoor dat u de hoeveelheid gratis rechten per kernuren kunt maximaliseren die u voor uw account krijgt.

Belangrijk

Zie GitHub Codespaces maandelijks inbegrepen opslag- en kernuren voor meer informatie over de rechten van uw GitHub-account.

  1. Meld u aan bij het GitHub Codespaces-dashboard (https://github.com/codespaces).

  2. Zoek uw momenteel uitgevoerde Codespaces die afkomstig zijn uit de Azure-Samples/azure-search-openai-demo GitHub-opslagplaats.

    Schermopname van alle actieve Codespaces, inclusief hun status en sjablonen.

  3. Open het contextmenu voor de coderuimte en selecteer Vervolgens Verwijderen.

    Schermopname van het contextmenu voor één coderuimte met de optie Verwijderen gemarkeerd.

Hulp vragen

Deze voorbeeldopslagplaats biedt informatie over probleemoplossing.

Probleemoplossing

Deze sectie biedt oplossingen voor problemen die specifiek zijn voor dit artikel.

Verificatietenant opgeven

Wanneer uw verificatie zich in een afzonderlijke tenant bevindt van uw hostingtoepassing, moet u die verificatietenant instellen met het volgende proces.

  1. Voer de volgende opdracht uit om het voorbeeld te configureren voor het gebruik van een tweede tenant voor de verificatietenant.

    azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
    Parameter Doel
    AZURE_AUTH_TENANT_ID Als AZURE_AUTH_TENANT_ID dit is ingesteld, is dit de tenant die als host fungeert voor de app.

  2. Implementeer de oplossing opnieuw met de volgende opdracht.

    azd up

Volgende stappen