Utilizzare controllo dell'accesso all'origine dati

Questa pagina descrive come applicare controllo dell'accesso all'origine dati per le app di ricerca in AI Applications.

Il controllo dell'accesso per le origini dati nelle applicazioni AI limita i dati che gli utenti possono visualizzare nei risultati dell'app di ricerca. Google utilizza il tuo provider di identità per identificare l'utente finale che esegue una ricerca e determinare se ha accesso ai documenti restituiti come risultati.

Ad esempio, supponiamo che i dipendenti della tua azienda cerchino nei documenti Confluence utilizzando l'app di ricerca. Tuttavia, devi assicurarti che non possano visualizzare contenuti tramite l'app a cui non è consentito l'accesso. Se hai configurato un pool di forza lavoro in Google Cloud per il provider di identità della tua organizzazione, puoi specificare anche quel pool di forza lavoro in AI Applications. Ora, se un dipendente utilizza la tua app, riceve risultati di ricerca solo per i documenti a cui il suo account ha già accesso in Confluence.

Informazioni sul controllo dell'accesso all'origine dati

L'attivazione del controllo dell'accesso è una procedura una tantum.

Il controllo dell'accesso è disponibile per Cloud Storage, BigQuery, Google Drive e tutte le origini dati di terze parti.

Per attivare controllo dell'accesso dell'accesso all'origine dati per le applicazioni di AI, devi aver configurato il provider di identità della tua organizzazione in Google Cloud. Sono supportati i seguenti framework di autenticazione:

  • Google Identity:

    • Scenario 1: se utilizzi Google Identity, tutte le identità e i gruppi di utenti sono presenti e gestiti tramite Google Cloud. Per saperne di più su Google Identity, consulta la rispettiva documentazione.

    • Scenario 2: utilizzi un provider di identità di terze parti e hai sincronizzato le identità con Google Identity. Gli utenti finali utilizzano Google Identity per autenticarsi prima di accedere alle risorse Google o a Google Workspace.

    • Scenario 3: utilizzi un provider di identità di terze parti e hai sincronizzato le identità con Google Identity. Tuttavia, continui a utilizzare il tuo provider di identità di terze parti esistente per eseguire l'autenticazione. Hai configurato SSO con Google Identity in modo che gli utenti inizino l'accesso utilizzando Google Identity e vengano poi indirizzati al tuo provider di identità di terze parti. Potresti aver già eseguito questa sincronizzazione durante la configurazione di altre risorse Google Cloud o di Google Workspace.

  • Federazione dei provider di identità di terze parti: se utilizzi un provider di identità esterno, ad esempio Azure AD, Okta o Ping, ma non vuoi sincronizzare le tue identità in Google Cloud Identity, devi configurare la federazione delle identità per la forza lavoro in Google Cloudprima di poter attivare controllo dell'accesso dell'accesso alle origini dati per le applicazioni di AI.

    Se utilizzi connettori di terze parti, l'attributo google.subject deve essere mappato al campo dell'indirizzo email nel provider di identità esterno. Di seguito sono riportati esempi di google.subject e google.groups mappature degli attributi per i provider di identità più utilizzati:

Limitazioni

Il controllo dell'accesso presenta le seguenti limitazioni:

  • Sono consentiti 3000 lettori per documento. Ogni entità viene conteggiata come lettore, dove un'entità può essere un gruppo o un singolo utente.
  • Puoi selezionare un provider di identità per ogni località supportata da Vertex AI Search.
  • Per impostare un'origine dati come controllata dall'accesso, devi selezionare questa impostazione durante la creazione del datastore. Non puoi attivare o disattivare questa impostazione per un datastore esistente.
  • La scheda Dati > Documenti nella console non mostra i dati per le origini dati con controllo dell'accesso perché questi dati devono essere visibili solo agli utenti che dispongono dell'accesso in visualizzazione.
  • Per visualizzare l'anteprima dei risultati dell'interfaccia utente per le app di ricerca che utilizzano il controllo dell'accesso di terze parti, devi accedere alla console federata o utilizzare l'app web. Vedi Visualizzare l'anteprima dei risultati per le app con controllo dell'accesso.

Prima di iniziare

Questa procedura presuppone che tu abbia configurato un provider di identità nel tuo progettoGoogle Cloud .

  • Identità Google: se utilizzi l'identità Google, puoi procedere alla procedura Connetti al tuo provider di identità.
  • Provider di identità di terze parti: assicurati di aver configurato un pool di identità per la forza lavoro per il tuo provider di identità di terze parti. Verifica di aver specificato i mapping degli attributi del soggetto e del gruppo durante la configurazione del pool di forza lavoro. Per informazioni sulle mappature degli attributi, consulta Mappature degli attributi nella documentazione IAM. Per maggiori informazioni sui pool di identità della forza lavoro, consulta Gestire i provider di pool di identità della forza lavoro nella documentazione di IAM.

Connettersi al provider di identità

Per specificare un provider di identità per le applicazioni AI e attivare il controllo dell'accesso dell'accesso all'origine dati:

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Applicazioni di AI

  2. Vai alla pagina Impostazioni > Autenticazione.

  3. Fai clic sull'icona di modifica per la località da aggiornare.

  4. Seleziona il tuo provider di identità nella finestra di dialogo Aggiungi provider di identità. Se selezioni un provider di identità di terze parti, seleziona anche il pool di forza lavoro che si applica alle tue origini dati.

  5. Fai clic su Salva modifiche.

Configurare un'origine dati con controllo dell'accesso

Per applicare il controllo dell'accesso a un'origine dati, segui questi passaggi a seconda del tipo di origine dati che stai configurando:

Dati non strutturati da Cloud Storage

Quando configuri un datastore per dati non strutturati da Cloud Storage, devi anche caricare i metadati ACL e impostare il datastore come controllato dall'accesso:

  1. Quando prepari i dati, includi le informazioni ACL nei metadati utilizzando il campo acl_info. Ad esempio:

    {    "id": "<your-id>",    "jsonData": "<JSON string>",    "content": {      "mimeType": "<application/pdf or text/html>",      "uri": "gs://<your-gcs-bucket>/directory/filename.pdf"    },    "acl_info": {      "readers": [        {          "principals": [            { "group_id": "group_1" },            { "user_id": "user_1" }          ]        }      ]    }  }

    Per saperne di più sui dati non strutturati con metadati, consulta la sezione Dati non strutturati di Preparare i dati per l'importazione.

  2. Quando segui i passaggi per la creazione del datastore in Crea un datastore di ricerca, puoi attivare controllo dell'accesso eseguendo le seguenti operazioni nella console o utilizzando l'API:

    • Console: quando crei un datastore, seleziona Questo datastore contiene controllo dell'accessoi accessi durante la creazione del datastore.
    • API: quando crei l'datastore, includi il flag "aclEnabled": "true" nel payload JSON.

  3. Quando segui i passaggi per l'importazione dei dati in Crea un archivio dati di ricerca, assicurati di fare quanto segue:

    • Carica i metadati con le informazioni ACL dallo stesso bucket dei dati non strutturati
    • Se utilizzi l'API, imposta GcsSource.dataSchema su document

Dati strutturati da Cloud Storage

Quando configuri un datastore per i dati strutturati da Cloud Storage, devi anche caricare i metadati ACL e impostare il datastore come controllato dall'accesso:

  1. Quando prepari i dati, includi le informazioni ACL nei metadati utilizzando il campo acl_info. Ad esempio:

    {    "id": "<your-id>",    "jsonData": "<JSON string>",    "acl_info": {      "readers": [        {          "principals": [            { "group_id": "group_1" },            { "user_id": "user_1" }          ]        }      ]    }  }

  2. Quando segui i passaggi per la creazione del datastore in Crea un datastore di ricerca, puoi attivare controllo dell'accesso eseguendo le seguenti operazioni nella console o utilizzando l'API:

    • Console: quando crei un datastore, seleziona Questo datastore contiene controllo dell'accessoi accessi durante la creazione del datastore.
    • API: quando crei l'datastore, includi il flag "aclEnabled": "true" nel payload JSON.

  3. Quando segui i passaggi per l'importazione dei dati in Crea un archivio dati di ricerca, assicurati di fare quanto segue:

    • Carica i metadati con le informazioni ACL dallo stesso bucket dei dati non strutturati
    • Se utilizzi l'API, imposta GcsSource.dataSchema su document

Dati non strutturati da BigQuery

Quando configuri un datastore per dati non strutturati da BigQuery, devi impostare il datastore come controllato dall'accesso e fornire i metadati ACL utilizzando uno schema predefinito per Vertex AI Search:

  1. Quando prepari i dati, specifica lo schema seguente. Non utilizzare uno schema personalizzato.

    [   {     "name": "id",     "mode": "REQUIRED",     "type": "STRING",     "fields": []   },   {     "name": "jsonData",     "mode": "NULLABLE",     "type": "STRING",     "fields": []   },   {     "name": "content",     "type": "RECORD",     "mode": "NULLABLE",     "fields": [       {         "name": "mimeType",         "type": "STRING",         "mode": "NULLABLE"       },       {         "name": "uri",         "type": "STRING",         "mode": "NULLABLE"       }     ]   }   {     "name": "acl_info",     "type": "RECORD",     "mode": "NULLABLE",     "fields": [       {         "name": "readers",         "type": "RECORD",         "mode": "REPEATED",         "fields": [           {             "name": "principals",             "type": "RECORD",             "mode": "REPEATED",             "fields": [               {                 "name": "user_id",                 "type": "STRING",                 "mode": "NULLABLE"               },               {                 "name": "group_id",                 "type": "STRING",                 "mode": "NULLABLE"               }             ]           }         ]       }     ]   } ]

  2. Includi i metadati ACL come colonna nella tabella BigQuery.

  3. Quando segui i passaggi descritti in Creare un archivio dati di ricerca, attiva ilcontrollo dell'accessoo nella console o utilizzando l'API:

    • Console: quando crei un datastore, seleziona Questo datastore contiene controllo dell'accessoi accessi durante la creazione del datastore.
    • API: quando crei l'datastore, includi il flag "aclEnabled": "true" nel payload JSON.

  4. Quando segui i passaggi per l'importazione dei dati in Crea un datastore di ricerca, se utilizzi l'API, imposta BigQuerySource.dataSchema su document.

Dati strutturati da BigQuery

Quando configuri un datastore per i dati strutturati di BigQuery, devi impostare il datastore come controllato dall'accesso e fornire i metadati ACL utilizzando uno schema predefinito per Vertex AI Search:

  1. Quando prepari i dati, specifica lo schema seguente. Non utilizzare uno schema personalizzato.

    [   {     "name": "id",     "mode": "REQUIRED",     "type": "STRING",     "fields": []   },   {     "name": "jsonData",     "mode": "NULLABLE",     "type": "STRING",     "fields": []   },   {     "name": "acl_info",     "type": "RECORD",     "mode": "NULLABLE",     "fields": [       {         "name": "readers",         "type": "RECORD",         "mode": "REPEATED",         "fields": [           {             "name": "principals",             "type": "RECORD",             "mode": "REPEATED",             "fields": [               {                 "name": "user_id",                 "type": "STRING",                 "mode": "NULLABLE"               },               {                 "name": "group_id",                 "type": "STRING",                 "mode": "NULLABLE"               }             ]           }         ]       }     ]   } ]

  2. Includi i metadati ACL come colonna nella tabella BigQuery.

  3. Quando segui i passaggi descritti in Creare un archivio dati di ricerca, attiva ilcontrollo dell'accessoo nella console o utilizzando l'API:

    • Console: quando crei un datastore, seleziona Questo datastore contiene controllo dell'accessoi accessi durante la creazione del datastore.
    • API: quando crei l'datastore, includi il flag "aclEnabled": "true" nel payload JSON.

  4. Quando segui i passaggi per l'importazione dei dati in Crea un datastore di ricerca, assicurati di fare quanto segue:

    • Se utilizzi la console, quando specifichi il tipo di dati che stai caricando, seleziona JSONL per dati strutturati con metadati.
    • Se utilizzi l'API, imposta BigQuerySource.dataSchema su document

Visualizzare l'anteprima dei risultati per le app con controllo dell'accesso di terze parti

Per visualizzare l'anteprima dei risultati nella console per le app con controllo dell'accesso dell'accesso di terze parti, devi accedere con le credenziali della tua organizzazione.

Puoi visualizzare l'anteprima dei risultati della UI in due modi:

Visualizzare l'anteprima dei risultati nella console della federazione delle identità della forza lavoro

Per utilizzare la console della federazione delle identità per la forza lavoro per visualizzare i risultati, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Applicazioni di AI

  2. Fai clic sul nome dell'app di ricerca di cui vuoi visualizzare l'anteprima dei risultati.

  3. Vai alla pagina Anteprima.

  4. Fai clic su Anteprima con identità federata per andare alla console di federazione delle identità della forza lavoro.

  5. Inserisci le credenziali del provider del pool di forza lavoro e dell'organizzazione.

  6. Visualizza l'anteprima dei risultati per la tua app nella pagina Anteprima visualizzata.

    Per saperne di più sull'anteprima dei risultati di ricerca, vedi Visualizzare i risultati di ricerca.

Per saperne di più sulla console della federazione delle identità per la forza lavoro, consulta Informazioni sulla console (federata).

Concedere le autorizzazioni di ricerca agli utenti

Per consentire agli utenti di cercare dati con controllo dell'accesso utilizzando la tua app, devi concedere l'accesso agli utenti del tuo dominio o del tuo pool di forza lavoro. Google consiglia di concedere un ruolo IAM personalizzato al tuo gruppo di utenti.

  • Identità Google: se utilizzi l'identità Google, Google consiglia di creare un gruppo Google che includa tutti i dipendenti che devono eseguire ricerche. Se sei un amministratore di Google Workspace, puoi includere tutti gli utenti di un'organizzazione in un gruppo Google seguendo i passaggi descritti in Aggiungere tutti gli utenti dell'organizzazione a un gruppo.
  • Provider di identità di terze parti: se utilizzi un provider di identità esterno, ad esempio Okta o Azure AD, aggiungi tutti i membri del pool di forza lavoro a un unico gruppo.

Google consiglia di creare un ruolo IAM personalizzato da concedere al gruppo di utenti, utilizzando le seguenti autorizzazioni:

  • discoveryengine.answers.get
  • discoveryengine.servingConfigs.answer
  • discoveryengine.servingConfigs.search
  • discoveryengine.sessions.get
  • discoveryengine.widgetConfigs.get

Per saperne di più sulle autorizzazioni per le risorse AI Applications utilizzando Identity and Access Management (IAM), consulta Controllo dell'accesso con IAM.

Per ulteriori informazioni sui ruoli personalizzati, consulta la sezione Ruoli personalizzati nella documentazione di IAM.

Autorizzare il widget di ricerca

Se vuoi implementare un widget di ricerca per un'app con controllo dell'accesso, segui questi passaggi:

  1. Concedi il ruolo Visualizzatore Discovery Engine agli utenti del tuo dominio o del tuo pool di forza lavoro che devono effettuare chiamate all'API Search.

  2. Genera token di autorizzazione da passare al widget:

  3. Segui i passaggi descritti in Aggiungere un widget con un token di autorizzazione per passare il token al widget.

Attivare l'app web

L'app web è un sito dedicato generato da Vertex AI Search in cui tu e qualsiasi altro utente con credenziali di accesso potete utilizzare l'app di ricerca.

Per fornire l'app di ricerca agli utenti senza dover integrare il widget di ricerca o l'API di ricerca nella tua applicazione, puoi fornire l'URL dell'app web ai tuoi utenti.

Per attivare l'app web, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Applicazioni di AI

  2. Fai clic sul nome dell'app di ricerca per cui creare un'app web.

    L'app di ricerca deve essere associata ad almeno un'origine dati con controllo dell'accesso. Per ulteriori informazioni, consulta la pagina Configurare un'origine dati con il controllo dell'accesso.

  3. Vai alla scheda Integrazione > UI.

  4. Fai clic su Abilita l'app web.

  5. Se utilizzi la federazione delle identità per la forza lavoro, seleziona un provider del pool di forza lavoro.

  6. Fai clic sul link alla tua app web.

  7. Inserisci le credenziali del provider del pool di forza lavoro e dell'organizzazione.

  8. Visualizza l'anteprima dei risultati per la tua app.

  9. Per configurare i risultati per l'app web, vai a Configurare i risultati per il widget di ricerca. Qualsiasi configurazione per il widget si applica anche all'app web.

  10. (Facoltativo) Per fornire l'app di ricerca ai tuoi utenti tramite questa app web dedicata, copia l'URL e invialo agli utenti che dispongono delle credenziali di accesso. Possono aggiungere l'URL dell'app web ai preferiti e accedervi per utilizzare l'app di ricerca.

Per saperne di più su come ottenere i risultati di ricerca, vedi Ottenere i risultati di ricerca.