Introduzione alla sicurezza dei documenti di chat per Python

Quando si compila un'applicazione di chat usando il modello RAG con i propri dati, assicurarsi che ogni utente riceva una risposta in base alle relative autorizzazioni. Seguire la procedura descritta in questo articolo per aggiungere il controllo di accesso ai documenti all'app di chat.

Un utente autorizzato deve avere accesso alle risposte contenute nei documenti dell'app di chat.

Screenshot dell'app di chat con risposta con l'accesso di autenticazione richiesto.

Un utente non autorizzato non deve avere accesso alle risposte da documenti protetti che non hanno l'autorizzazione per visualizzare.

Screenshot dell'app chat con la risposta che indica che l'utente non ha accesso ai dati.

Nota

Questo articolo usa uno o più modelli di app di intelligenza artificiale come base per gli esempi e le linee guida nell’articolo. I modelli di app di intelligenza artificiale offrono implementazioni di riferimento ben gestite e facili da distribuire per garantire un punto di partenza di alta qualità per le app di intelligenza artificiale.

Panoramica dell'architettura

Senza la funzionalità di sicurezza dei documenti, l'app di chat aziendale ha un'architettura semplice usando Ricerca di intelligenza artificiale di Azure e Azure OpenAI. Una risposta viene determinata dalle query a Ricerca di intelligenza artificiale di Azure in cui vengono archiviati i documenti, in combinazione con una risposta da un modello GPT di Azure OpenAI. In questo semplice flusso non viene usata alcuna autenticazione utente.

Diagramma dell'architettura che mostra una risposta determinata dalle query a Ricerca di intelligenza artificiale di Azure in cui sono archiviati i documenti, in combinazione con una risposta di richiesta da Azure OpenAI.

Per aggiungere sicurezza per i documenti, è necessario aggiornare l'app di chat aziendale:

  • Aggiungere l'autenticazione client all'app di chat con Microsoft Entra.
  • Aggiungere la logica lato server per popolare un indice di ricerca con accesso utente e gruppo.

Diagramma dell'architettura che mostra un uso dell'autenticazione con Microsoft Entra ID, quindi passando tale autenticazione a Ricerca di intelligenza artificiale di Azure.

Ricerca di intelligenza artificiale di Azure non fornisce autorizzazioni native a livello di documento e non può variare i risultati della ricerca dall'interno di un indice in base alle autorizzazioni utente. L'applicazione può invece usare filtri di ricerca per garantire che un documento sia accessibile a un utente specifico o a un gruppo specifico. All'interno dell'indice di ricerca, ogni documento deve avere un campo filtrabile che archivia le informazioni sull'identità dell'utente o del gruppo.

Diagramma dell'architettura che mostra che per proteggere i documenti in Ricerca di intelligenza artificiale di Azure, ogni documento include l'autenticazione utente, che viene restituita nel set di risultati.

Poiché l'autorizzazione non è contenuta in modo nativo in Ricerca di intelligenza artificiale di Azure, è necessario aggiungere un campo per contenere informazioni sull'utente o sul gruppo, quindi filtrare i documenti che non corrispondono. Per implementare questa tecnica, è necessario:

  • Creare un campo di controllo di accesso al documento nell'indice dedicato all'archiviazione dei dettagli di utenti o gruppi con accesso ai documenti.
  • Popolare il campo di controllo di accesso del documento con i dettagli dell'utente o del gruppo pertinenti.
  • Aggiornare questo campo di controllo di accesso ogni volta che vengono apportate modifiche alle autorizzazioni di accesso a utenti o gruppi.
  • Se gli aggiornamenti dell'indice sono pianificati con un indicizzatore, le modifiche vengono prelevate nell'esecuzione successiva dell'indicizzatore. Se non si usa un indicizzatore, è necessario reindicizzare manualmente.

In questo articolo il processo di protezione dei documenti in Ricerca di intelligenza artificiale di Azure è reso possibile con gli script di esempio eseguiti dall'amministratore della ricerca. Gli script associano un singolo documento a una singola identità utente. È possibile accettare questi script e applicare requisiti di sicurezza e produzione personalizzati per adattarli alle proprie esigenze.

Determinare la configurazione della sicurezza

La soluzione fornisce variabili di ambiente booleane per attivare le funzionalità necessarie per la sicurezza dei documenti in questo esempio.

Parametro Scopo
AZURE_USE_AUTHENTICATION Se impostato su true, abilita l'accesso utente all'app di chat e servizio app l'autenticazione. Abilita Use oid security filter nelle impostazioni sviluppatore dell'app di chat.
AZURE_ENFORCE_ACCESS_CONTROL Se impostato su true, richiede l'autenticazione per qualsiasi accesso ai documenti. Le impostazioni sviluppatore per la sicurezza dell'oid e del gruppo verranno attivate e disabilitate in modo che non possano essere disabilitate dall'interfaccia utente.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS Se impostata su true, questa impostazione consente agli utenti autenticati di cercare nei documenti senza controlli di accesso assegnati, anche quando è necessario il controllo di accesso. Questo parametro deve essere usato solo quando AZURE_ENFORCE_ACCESS_CONTROL è abilitato.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS Se impostata su true, questa impostazione consente agli utenti non autenticati di usare l'app, anche quando viene applicato il controllo di accesso. Questo parametro deve essere usato solo quando AZURE_ENFORCE_ACCESS_CONTROL è abilitato.

Usare le sezioni seguenti per comprendere i profili di sicurezza supportati in questo esempio. Questo articolo configura il profilo Enterprise.

Enterprise: account obbligatorio e filtro documento

Ogni utente del sito deve accedere e il sito contiene contenuto pubblico per tutti gli utenti. Il filtro di sicurezza a livello di documento viene applicato a tutte le richieste.

Variabili di ambiente:

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

Uso misto: account facoltativo e filtro documento

Ogni utente del sito può accedere e il sito contiene contenuto pubblico per tutti gli utenti. Il filtro di sicurezza a livello di documento viene applicato a tutte le richieste.

Variabili di ambiente:

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

Prerequisiti

Per completare questo articolo è disponibile un ambiente contenitore di sviluppo con tutte le dipendenze necessarie. Puoi eseguire il contenitore di sviluppo in GitHub Codespaces (in un browser) o in locale usando Visual Studio Code.

Per usare questo articolo, sono necessari i prerequisiti seguenti:

Sono necessari altri prerequisiti a seconda dell'ambiente di sviluppo preferito.

Ambiente di sviluppo aperto

Inizia ora con un ambiente di sviluppo che ha tutte le dipendenze installate per completare questo articolo.

GitHub Codespaces esegue un contenitore di sviluppo gestito da GitHub con Visual Studio Code per il Web come interfaccia utente. Per l'ambiente di sviluppo più semplice, usa GitHub Codespaces per avere gli strumenti di sviluppo e le dipendenze corretti preinstallati per completare questo articolo.

Importante

Tutti gli account GitHub possono usare Codespaces per un massimo di 60 ore gratuite ogni mese con 2 istanze di core. Per altre informazioni, vedere Spazio di archiviazione e ore core mensili inclusi in GitHub Codespaces.

  1. Avviare il processo per creare un nuovo codespace GitHub nel ramo main del repository GitHub Azure-Samples/azure-search-openai-demo.

  2. Fai clic con il pulsante destro del mouse sul pulsante seguente e scegli Apri collegamento in nuove finestre per avere a disposizione allo stesso tempo sia l'ambiente di sviluppo che la documentazione.

    Aprire in GitHub Codespaces

  3. Nella pagina Crea codespace esaminare le impostazioni di configurazione del codespace e quindi selezionare Crea nuovo codespace

    Screenshot della schermata di conferma prima di creare un nuovo codespace.

  4. Attendere l'avvio del codespace. Questo processo di avvio può richiedere alcuni minuti.

  5. Nel terminale nella parte inferiore della schermata, accedi ad Azure con Azure Developer CLI.

    azd auth login
    
  6. Completare il processo di autenticazione.

  7. Le attività rimanenti in questo articolo vengono eseguite nel contesto di questo contenitore di sviluppo.

Ottenere informazioni necessarie con l'interfaccia della riga di comando di Azure

Ottenere l'ID sottoscrizione e l'ID tenant con il comando dell'interfaccia della riga di comando di Azure seguente. Copiare il valore da usare come AZURE_TENANT_ID.

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

Se viene visualizzato un errore relativo ai criteri di accesso condizionale del tenant, è necessario un secondo tenant senza criteri di accesso condizionale.

  • Il primo tenant, associato all'account utente, viene usato per la AZURE_TENANT_ID variabile di ambiente.
  • Il secondo tenant, senza accesso condizionale, viene usato per la AZURE_AUTH_TENANT_ID variabile di ambiente per accedere a Microsoft Graph. Per i tenant con criteri di accesso condizionale, trovare l'ID di un secondo tenant senza criteri di accesso condizionale o creare un nuovo tenant.

Impostare le variabili di ambiente

  1. Eseguire i comandi seguenti per configurare l'applicazione per il profilo 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. Eseguire il comando seguente per impostare il tenant, che autorizza l'accesso dell'utente all'ambiente dell'applicazione ospitata. Sostituire <YOUR_TENANT_ID> con l'ID tenant.

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
    

Nota

Se si dispone di un criterio di accesso condizionale nel tenant utente, è necessario specificare un tenant di autenticazione.

Distribuire l'app di chat in Azure

La distribuzione include la creazione delle risorse di Azure, il caricamento dei documenti, la creazione delle app di identità Di Microsoft Entra (client e server) e l'attivazione dell'identità per la risorsa di hosting.

  1. Esegui il seguente comando Azure Developer CLI per effettuare il provisioning delle risorse di Azure e distribuire il codice sorgente:

    azd up
    
  2. Usare la tabella seguente per rispondere alle richieste di distribuzione azd:

    Richiesta Risposta
    Nome ambiente Usare un nome breve con informazioni di identificazione, ad esempio l'alias e l'app: tjones-secure-chat.
    Subscription Selezionare una sottoscrizione in cui creare le risorse.
    Località per le risorse di Azure Selezionare una località nelle vicinanze.
    Posizione per documentIntelligentResourceGroupLocation Selezionare una località nelle vicinanze.
    Posizione per openAIResourceGroupLocation Selezionare una località nelle vicinanze.

    Attendere 5 o 10 minuti dopo la distribuzione dell'app per consentire l'avvio dell'app.

  3. Dopo che l'applicazione è stata distribuita correttamente, viene visualizzato un URL nel terminale.

  4. Seleziona l'URL etichettato (✓) Done: Deploying service webapp per aprire l'applicazione di chat in un browser.

    Screenshot dell'app di chat nel browser che mostra diversi suggerimenti per l'inserimento in chat e la casella di testo della chat per inserire una domanda.

  5. Accettare il popup di autenticazione dell'app.

  6. Quando viene visualizzata l'app di chat, si noti nell'angolo superiore destro che l'utente ha eseguito l'accesso.

  7. Aprire Le impostazioni sviluppatore e notare che entrambe le opzioni sono selezionate e disattivate (disabilitate per la modifica).

    • Usare il filtro di sicurezza oid
    • Usare il filtro di sicurezza dei gruppi
  8. Selezionare la scheda con What does a product manager do?.

  9. Si ottiene una risposta simile alla seguente: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

    Screenshot dell'app chat nel browser che mostra che la risposta non può essere restituita

Aprire l'accesso a un documento per un utente

Attivare le autorizzazioni per il documento esatto in modo da ottenere la risposta. Queste informazioni richiedono diverse informazioni:

  • Archiviazione di Azure
    • Nome conto
    • Nome contenitore
    • URL BLOB/documento per role_library.pdf
  • ID utente in Microsoft Entra ID

Dopo aver conosciuto queste informazioni, aggiornare il campo dell'indice oids di Ricerca intelligenza artificiale di Azure per il role_library.pdf documento.

Ottenere l'URL per un documento nell'archiviazione

  1. .azure Nella cartella nella radice del progetto individuare la directory dell'ambiente e aprire il .env file con tale directory.

  2. Cercare la AZURE_STORAGE_ACCOUNT voce e copiarne il valore.

  3. Usare i comandi seguenti dell'interfaccia della riga di comando di Azure per ottenere l'URL del BLOB role_library.pdf nel contenitore del contenuto .

    az storage blob url \
        --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
        --container-name 'content' \
        --name 'role_library.pdf' 
    
    Parametro Scopo
    --account-name Nome dell'account di archiviazione di Azure
    --container-name Il nome del contenitore in questo esempio è content
    --name Il nome del BLOB in questo passaggio è role_library.pdf
  4. Copiare l'URL del BLOB da usare in un secondo momento.

Ottenere l'ID utente

  1. Nell'app chap selezionare Impostazioni sviluppatore.
  2. Nella sezione Attestazioni token ID copiare objectidentifier. Questa operazione è nota nella sezione successiva come USER_OBJECT_ID.
  1. Usare lo script seguente per modificare il oids campo in Ricerca di intelligenza artificiale di Azure per role_library.pdf in modo da potervi accedere.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action add \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Parametro Scopo
    -v Output dettagliato.
    --acl-type ID oggetto gruppo o utente (OID): oids
    --acl-action Aggiungere a un campo dell'indice di ricerca. Altre opzioni includono remove, remove_all, list.
    --Acl Gruppo o utente USER_OBJECT_ID
    --URL Percorso del file in Archiviazione di Azure, ad esempio https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Non racchiudere l'URL tra virgolette nel comando dell'interfaccia della riga di comando.
  2. L'output della console per questo comando è simile al seguente:

    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. Facoltativamente, usare il comando seguente per verificare che l'autorizzazione sia elencata per il file in Ricerca di intelligenza artificiale di Azure.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action list \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Parametro Scopo
    -v Output dettagliato.
    --acl-type Gruppo o utente (oid): oids
    --acl-action Elencare un campo oidsdell'indice di ricerca . Altre opzioni includono remove, remove_all, list.
    --Acl Gruppo o utente USER_OBJECT_ID
    --URL Percorso del file in Archiviazione di Azure, ad esempio https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Non racchiudere l'URL tra virgolette nel comando dell'interfaccia della riga di comando.
  4. L'output della console per questo comando è simile al seguente:

    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]
    

    La matrice alla fine dell'output include il USER_OBJECT_ID e viene usata per determinare se il documento viene usato nella risposta con Azure OpenAI.

Verificare che Ricerca di intelligenza artificiale di Azure contenga i USER_OBJECT_ID

  1. Aprire il portale di Azure e cercare .AI Search

  2. Selezionare la risorsa di ricerca dall'elenco.

  3. Selezionare Gestione della ricerca -> Indici.

  4. Selezionare il gptkbindex.

  5. Selezionare Visualizza -> Visualizzazione JSON.

  6. Sostituire json con il codice JSON seguente.

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

    In questo modo vengono cercati tutti i documenti in cui il oids campo ha qualsiasi valore e restituisce i sourcefilecampi e oids .

  7. Se l'oggetto role_library.pdf non dispone dell'oid, tornare alla sezione Fornire l'accesso utente a un documento in Ricerca di Azure e completare i passaggi.

Verificare l'accesso utente al documento

Se sono stati completati i passaggi ma non è stata visualizzata la risposta corretta, verificare che il USER_OBJECT_ID sia impostato correttamente in Ricerca di intelligenza artificiale di Azure per tale role_library.pdf.

  1. Tornare all'app di chat. Potrebbe essere necessario eseguire di nuovo l'accesso.

  2. Immettere la stessa query in modo che il role_library contenuto venga usato nella risposta OpenAI di Azure: What does a product manager do?.

  3. Visualizzare il risultato, che include ora la risposta appropriata dal documento della raccolta ruoli.

    Screenshot dell'app chat nel browser che mostra che viene restituita la risposta.

Pulire le risorse

Pulire le risorse di Azure

Le risorse di Azure create in questo articolo vengono fatturate alla sottoscrizione di Azure. Se prevedi che queste risorse non ti servano in futuro, eliminale per evitare di incorrere in costi aggiuntivi.

Esegui il seguente comando Azure Developer CLI per eliminare le risorse di Azure e rimuovere il codice sorgente:

azd down --purge

Pulire GitHub Codespaces

L'eliminazione dell'ambiente GitHub Codespaces offre la possibilità di aumentare le ore gratuite per core a cui si ha diritto per l'account.

Importante

Per altre informazioni sui diritti dell'account GitHub, vedere Ore di archiviazione e di core mensili incluse in GitHub Codespaces.

  1. Accedere al dashboard di GitHub Codespaces (https://github.com/codespaces).

  2. Individuare i codespace attualmente in esecuzione provenienti dal repository GitHub Azure-Samples/azure-search-openai-demo.

    Screenshot di tutti i codespace in esecuzione, inclusi lo stato e i modelli.

  3. Aprire il menu di scelta rapida per il codespace e selezionare Elimina.

    Screenshot del menu di scelta rapida per un singolo codespace con l'opzione di eliminazione evidenziata.

Come ottenere assistenza

Questo repository di esempio offre informazioni sulla risoluzione dei problemi.

Risoluzione dei problemi

Questa sezione offre la risoluzione dei problemi specifici di questo articolo.

Specificare il tenant di autenticazione

Quando l'autenticazione si trova in un tenant separato dall'applicazione di hosting, è necessario impostare tale tenant di autenticazione con il processo seguente.

  1. Eseguire il comando seguente per configurare l'esempio in modo da usare un secondo tenant per il tenant di autenticazione.

    azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
    
    Parametro Scopo
    AZURE_AUTH_TENANT_ID Se AZURE_AUTH_TENANT_ID è impostato, è il tenant che ospita l'app.
  2. Ridistribuire la soluzione con il comando seguente.

    azd up
    

Passaggi successivi