Configurare controllo dell'accesso'origine dati

Questa pagina descrive come applicare il controllo dell'accesso all'origine dati per le app di ricerca in Ricerca agente.

Il controllo dell'accesso alle origini dati in Ricerca agente 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 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 nel Google Cloud provider di identità della tua organizzazione, allora puoi specificare anche quel pool di forza lavoro in Ricerca agente. 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 il controllo dell'accesso all'origine dati per Ricerca agente, devi aver configurato il provider di identità della tua organizzazione in Google Cloud. Sono supportati i seguenti framework di autenticazione:

  • Google Identity:

    • Caso 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 documentazione di Google Identity.

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

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

  • Federazione dei provider di identità di terze parti: se utilizzi un provider di identità esterno , ad esempio Microsoft Entra ID, Okta o Ping, ma non vuoi sincronizzare le identità in Google Cloud Identity, devi configurare la federazione delle identità per la forza lavoro in Google Cloud prima di poter attivare controllo dell'accesso dell'accesso all'origine dati per Ricerca agente.

    Se utilizzi connettori di terze parti, l' google.subject attributo deve essere mappato al campo dell'indirizzo email nel provider di identità esterno. Di seguito sono riportati esempi di mappatura 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 3000 lettori per documento. Ogni entità viene conteggiata come lettore. Un'entità può essere un gruppo o un singolo utente.
  • Puoi selezionare un provider di identità per ogni località supportata da Ricerca agente.
  • 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 controllate dall'accesso perché questi dati devono essere visibili solo agli utenti che hanno 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. 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 Google Cloud progetto.

  • Google Identity: se utilizzi Google Identity, 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 le mappature degli attributi di soggetto e attributo di gruppo durante la configurazione del pool di forza lavoro. Per informazioni sulle mappature degli attributi, consulta Mappature degli attributi nella documentazione di IAM. Per saperne di più sui pool di identità per la forza lavoro, consulta Gestire i provider di pool di identità per la forza lavoro nella documentazione di IAM.

Connetti al tuo provider di identità

Per specificare un provider di identità per Ricerca agente e attivare il controllo dell'accesso all'origine dati:

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

    AI Applications

  2. Vai alla pagina Impostazioni > Autenticazione.

  3. Fai clic sull'icona di modifica per la località che vuoi 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.

Configura un'origine dati con il 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 i 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 Creare un datastore di ricerca, puoi attivare il controllo dell'accesso eseguendo le seguenti operazioni nella console o utilizzando l'API:

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

  3. Quando segui i passaggi per l'importazione dei dati in Creare un datastore di ricerca, assicurati di eseguire 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 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 Creare un datastore di ricerca, puoi attivare il controllo dell'accesso eseguendo le seguenti operazioni nella console o utilizzando l'API:

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

  3. Quando segui i passaggi per l'importazione dei dati in Creare un datastore di ricerca, assicurati di eseguire 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 da BigQuery, devi impostare il datastore come controllato dall'accesso e fornire i metadati ACL utilizzando uno schema predefinito per Ricerca agente:

  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 datastore di ricerca, attiva il controllo dell'accesso nella console o utilizzando l'API:

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

  4. Quando segui i passaggi per l'importazione dei dati in Creare 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 da BigQuery, devi impostare il datastore come controllato dall'accesso e fornire i metadati ACL utilizzando uno schema predefinito per Ricerca agente:

  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 datastore di ricerca, attiva il controllo dell'accesso nella console o utilizzando l'API:

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

  4. Quando segui i passaggi per l'importazione dei dati in Creare un datastore di ricerca, assicurati di eseguire 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

Visualizza l'anteprima dei risultati nella console della federazione delle identità per la forza lavoro

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

Per visualizzare l'anteprima dei risultati dell'interfaccia utente:

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

    AI Applications

  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à per la 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ù sulla visualizzazione dell'anteprima dei risultati di ricerca, consulta Visualizzare i risultati di ricerca.

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

Concedi le autorizzazioni di ricerca agli utenti

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

  • Google Identity: se utilizzi Google Identity, 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 Microsoft Entra ID, aggiungi tutti gli utenti del pool di forza lavoro a un singolo 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 di Ricerca agente che utilizzano Identity and Access Management (IAM), consulta Controllo dell'accesso con IAM.

Per saperne di più sui ruoli personalizzati, consulta la sezione Ruoli personalizzati in nella documentazione di IAM.

Autorizza il widget di ricerca

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

  1. Concedi il ruolo Visualizzatore di Discovery Engine agli utenti nel tuo dominio o 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.

Passaggi successivi

Visualizza i risultati di ricerca.