Utilizzare controllo dell'accesso all'origine dati

Questa pagina descrive come applicare controllo dell'accesso alle origini dati per le app di ricerca in Vertex AI Agent Builder.

Il controllo dell'accesso per le origini dati in Vertex AI Agent Builder 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 di Confluence utilizzando la tua app di ricerca. Tuttavia, devi assicurarti che non possano visualizzare contenuti tramite l'app a cui non sono autorizzati ad accedere. Se hai configurato un pool di forza lavoro in Google Cloud per il provider di identità della tua organizzazione, puoi anche specificare quel pool di forza lavoro in Vertex AI Agent Builder. Ora, se un impiegato 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 il controllo dell'accesso alle origini dati per Vertex AI Agent Builder, devi avere configurato il provider di identità della tua organizzazione in Google Cloud. Sono supportati i seguenti framework di autenticazione:

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

  • Federazione di provider di identità di terze parti: se utilizzi un provider di identità esterno, ad esempio Okta o Azure AD, devi configurare la federazione delle identità per la forza lavoro in Google Cloud prima di poter attivare controllo dell'accesso alle origini dati per Vertex AI Agent Builder.

    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 alcuni esempi di mappature degli attributi google.subject e google.groups per i provider di identità di uso comune:

Limitazioni

Il controllo dell'accesso presenta le seguenti limitazioni:

  • Sono consentiti 250 lettori per documento. Ogni entità viene conteggiata come un 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.
  • Il controllo dell'accesso viene rispettato solo per le identità e i gruppi definiti esplicitamente nel tuo provider di identità. Le identità o i gruppi definiti in modo nativo all'interno di app di terze parti non sono supportati.
  • Per impostare un'origine dati come con controllo dell'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 accesso controllato 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 di accesso di terze parti, devi accedere alla console federata o utilizzare l'app web. Consulta 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 progetto Google Cloud.

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

Connettiti al tuo provider di identità

Per specificare un provider di identità per Vertex AI Agent Builder e attivare controllo dell'accesso dell'accesso alle origini dati:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

  2. Vai alla pagina Impostazioni > Autenticazione.

  3. Fai clic su Aggiungi provider di identità per la sede da aggiornare.

  4. Seleziona il tuo provider di identità nella finestra di dialogo Aggiungi provider di identità. Se selezione un provider di identità di terze parti, seleziona anche il pool di personale applicabile 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 i passaggi riportati di seguito a seconda del tipo di origine dati che stai configurando:

Dati non strutturati da Cloud Storage

Quando configuri un datastore per i dati non strutturati di Cloud Storage, devi caricare anche i metadati ACL e impostare il data store 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 Creare un datastore di dati di ricerca, puoi attivare il controllo dell'accesso svolgendo i seguenti passaggi nella console o utilizzando l'API:

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

  3. Quando segui i passaggi per l'importazione dei dati in Creare un magazzino di dati di ricerca, assicurati di svolgere le seguenti operazioni:

    • 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 caricare anche i metadati ACL e impostare il data store come con controllo dell'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 Creare un datastore di dati di ricerca, puoi attivare il controllo dell'accesso svolgendo i seguenti passaggi nella console o utilizzando l'API:

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

  3. Quando segui i passaggi per l'importazione dei dati in Creare un magazzino di dati di ricerca, assicurati di svolgere le seguenti operazioni:

    • 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 i dati non strutturati di BigQuery, devi impostarlo come controllato dall'accesso e fornire i metadati ACL utilizzando uno schema predefinito per la ricerca Vertex AI:

  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 magazzino di dati di ricerca, attiva controllo dell'accesso nella console o tramite l'API:

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

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

Dati strutturati di BigQuery

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

  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 magazzino di dati di ricerca, attiva controllo dell'accesso nella console o tramite l'API:

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

  4. Quando segui i passaggi per l'importazione dei dati in Creare un datastore per la ricerca, assicurati di svolgere le seguenti operazioni:

    • 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 dell'interfaccia utente in due modi:

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

Per utilizzare la console Workforce Identity Federation per visualizzare i risultati:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

  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 accedere alla console della 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 ulteriori informazioni sull'anteprima dei risultati di ricerca, consulta Ricevere i risultati di ricerca.

Per saperne di più sulla console Workforce Identity Federation, consulta Informazioni sulla console (federata).

Concedere le autorizzazioni di ricerca agli utenti

Per consentire agli utenti di cercare i dati con accesso controllato utilizzando la tua app, devi concedere l'accesso agli utenti del tuo dominio o del tuo pool di personale. Google consiglia di concedere un ruolo IAM personalizzato al 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

Per ulteriori informazioni sulle autorizzazioni per le risorse di Vertex AI Agent Builder che utilizzano 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 accesso controllato, segui questi passaggi:

  1. Concedi il ruolo Visualizzatore del motore di ricerca agli utenti del tuo dominio o del tuo pool di personale che devono effettuare chiamate all'API di ricerca.

  2. Genera i 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.

Attiva l'app web

L'app web è un sito dedicato generato da Vertex AI Search in cui tu e qualsiasi altro utente con le 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:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

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

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

  3. Vai alla scheda Integrazione > UI.

  4. Fai clic su Attiva l'app web.

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

  6. Fai clic sul link all'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. Eventuali configurazioni per il widget si applicano anche all'app web.

  10. (Facoltativo) Per fornire l'app di ricerca agli 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 aprirlo per utilizzare la tua app di ricerca.

Per ulteriori informazioni su come ottenere i risultati di ricerca, consulta Ottenere i risultati di ricerca.