Gestisci il controllo dell'accesso

Questa pagina fornisce una panoramica su come gestire controllo dell'accesso per progetti e documenti.

Panoramica del controllo dell'accesso ai dati

Il controllo dell'accesso ai dati è una funzionalità chiave di Document AI Warehouse. Controlla chi ha accesso a quale risorsa in Document AI Warehouse e il livello di accesso.

Le API Document AI Warehouse sono basate su Google Cloud. Il protocollo HTTPS viene utilizzato per garantire la trasmissione sicura dei dati su internet. L'autenticazione e l'autorizzazione vengono applicate alle API Document AI Warehouse per proteggere il servizio e i dati utente in base alle identità Google.

Le API Document AI Warehouse utilizzano OAuth2 per l'autenticazione con un account utente. Tutti i metodi API richiedono l'ambito OAuth https://www.googleapis.com/auth/cloud-platform.

Document AI Warehouse applica il controllo dell'accesso ai dati dei clienti in base a Cloud IAM. Document AI Warehouse definisce un insieme di ruoli e autorizzazioni associate per consentirti di limitare l'accesso di diversi utenti ai dati archiviati nel nostro servizio. Per saperne di più, consulta la sezione Ruoli e autorizzazioni IAM.

Utilizzare un account di servizio per applicare controllo dell'accesso di base

Hai bisogno di un service account a cui sono state concesse le autorizzazioni necessarie per accedere all'API Document AI Warehouse. Se segui il passaggio "Provisioning tramite la console Google Cloud " nella guida Guida rapida, viene eseguito automaticamente il provisioning di un account di servizio con il ruolo Amministratore di Document AI Warehouse.

Modalità di controllo dell'accesso

Document AI Warehouse fornisce tre modalità di controllo dell'accesso:

  • Accesso universale: nessun controllo dell'accesso a livello di documento
  • Controllo dell'accesso a livello di documento con il tuo servizio di identità
  • Controllo dell'accesso a livello di documento con Cloud Identity

Gli utenti devono scegliere una delle modalità di accesso durante il processo di provisioning. Le sezioni seguenti descrivono la differenza tra le tre modalità di controllo dell'accesso'accesso e mostrano come attivare ciascuna modalità.

Accesso universale

Controllo dell'accesso universale ti consente di utilizzare Identity and Access Management (IAM) da solo per gestire le autorizzazioni. IAM applica le stesse autorizzazioni a tutti i documenti nel progetto con l'identità autenticata.

In questa modalità, al termine della procedura di provisioning nella guida Guida rapida, tu e tutti i tuoi utenti potete accedere a tutti i documenti del progetto Google Cloudselezionato nel servizio Document AI Warehouse utilizzando il account di servizio, con le autorizzazioni associate al account di servizio.

Il resto di questo documento descrive controllo dell'accesso a livello di documento. Se utilizzi l'accesso universale, puoi ignorare il resto del documento.

Controllo dell'accesso a livello di documento

Per gli utenti di Document AI Warehouse, puoi:

  • Utilizzare il proprio servizio di identità
    • Sono necessari sia l'utente finale sia i gruppi di utenti finali nei metadati della richiesta. Se la tua azienda ha un proprio modo di autenticare l'utente e identificare i gruppi a cui appartiene, utilizza questa opzione.
  • Utilizza Cloud Identity
    • Nei metadati della richiesta è necessario solo l'utente finale perché Document AI Warehouse raccoglie i gruppi di appartenenza da Cloud Identity per i clienti. La differenza tra questa opzione e l'utilizzo di un servizio di identità personalizzato è che gestisci le appartenenze ai gruppi dell'utente utilizzando Cloud Identity anziché un sistema interno.

L'utilizzo della modalità di accesso a livello di documento presenta alcune limitazioni:

  • Sono supportati solo i membri e i ruoli nell'ACL. Le condizioni IAM vengono ignorate.
  • I ruoli personalizzati non sono supportati nell'elenco di controllo dell'accesso.
  • Document AI Warehouse non verifica le credenziali dell'utente finale. Document AI Warehouse verifica solo le credenziali del account di servizio per assicurarsi che le chiamate provengano dai clienti. Le credenziali utente finale devono essere verificate dal cliente.
  • I clienti devono fornire l'utente finale (e tutti i gruppi di cui l'utente finale è membro se non utilizza l'opzione Cloud Identity) nei metadati della richiesta per applicare icontrollo dell'accessol'accesso.
  • Il numero di gruppi di appartenenza per l'utente finale deve essere inferiore a 100.

Controllo dell'accesso a livello di documento con il servizio di identità del cliente

Puoi scegliere questa modalità se vuoi:

  • Concedi a gruppi di utenti finali autorizzazioni diverse per accedere a ciascuno dei documenti.
  • Utilizza il tuo servizio di identità.

Questa modalità ti consente di utilizzare IAM e elenchi di controllo dell'accesso (ACL) insieme per gestire le autorizzazioni. Ogni documento in Document AI Warehouse può essere configurato con un'ACL a livello di documento specifica. L'autenticazione e l'autorizzazione avvengono come segue:

  • Le credenziali del account di servizio sono autenticate e autorizzate ad accedere al servizio.
  • Nei metadati della richiesta, includi l'utente finale e i gruppi di appartenenza dell'utente finale. L'utente finale o almeno uno dei gruppi a cui appartiene deve disporre dell'autorizzazione per accedere al documento.

Document AI Warehouse concede l'accesso al documento richiesto solo se sono soddisfatte entrambe le condizioni nell'elenco precedente.

L'UserInfo (inclusi l'ID utente finale e gli ID gruppo di appartenenza dell'utente) di RequestMetadata fornito nella chiamata API viene utilizzato per verificare se l'utente finale è autorizzato a eseguire l'azione corrispondente sulla risorsa documento richiesta. Ad esempio, il UserInfo fornito nell'API GetDocument viene utilizzato per verificare se l'utente finale è autorizzato a visualizzare il documento. Se l'utente finale o uno dei gruppi di appartenenza è autorizzato a visualizzare il documento, l'utente finale è autorizzato a visualizzare il documento.

Esempio di RequestMetadata in formato JSON:

request_metadata: {
    user_info: {
        id: user:fake_user_id
        group_ids: [
            group:fake_group_id_1,
            group:fake_group_id_2,
            group:fake_group_id_3,
        ]
    }
}

Oltre a seguire la guida Guida rapida, questa modalità di controllo dell'accesso#39;accesso richiede alcuni passaggi aggiuntivi prima di iniziare a inviare API a Document AI Warehouse:

  1. Recupera le iscrizioni ai gruppi per un determinato utente finale dal tuo servizio directory (ad esempio Azure Active Directory o Okta).
  2. Segui le istruzioni riportate nella sezione Configura il controllo dell'accesso per impostare un criterio di progetto predefinito. Puoi anche impostare un ACL a livello di documento per documenti specifici dopo la creazione.

Dopo aver completato i passaggi precedenti, puoi utilizzare l'account di servizio per effettuare chiamate API a Document AI Warehouse con informazioni sull'utente finale e sull'appartenenza al gruppo nella sezione RequestMetadata del corpo della richiesta.

In questa modalità, devi implementare un proxy per autenticare e autorizzare gli utenti finali. Il proxy utilizza l'account di servizio a cui è stato concesso il ruolo di amministratore per accedere al servizio. La chiave del account di servizio deve essere protetta in modo che venga utilizzata solo dal proxy.

Come soluzione predefinita, la console Document AI Warehouse è un proxy che può archiviare la chiave del account di servizio, autenticare gli utenti finali tramite le identità Google e inoltrare le richieste a Document AI Warehouse.

Controllo dell'accesso a livello di documento con Cloud Identity

In alternativa all'utilizzo del tuo servizio di identità, puoi anche scegliere di utilizzare Cloud Identity per semplificare la procedura.

Per gestire centralmente utenti e gruppi, Google Cloud i clienti possono configurare Cloud Identity da zero o federare le identità tra Google e altri provider di identità, come Active Directory e Azure Active Directory.

La sezione UserInfo di RequestMetadata fornita nella chiamata API viene utilizzata per verificare se l'utente finale è autorizzato a eseguire l'azione corrispondente sulla risorsa del documento richiesta. Utilizzando Cloud Identity, nell'RequestMetadata è richiesto solo l'ID utente finale e Document AI Warehouse raccoglie le informazioni sul gruppo di appartenenza dal servizio Cloud Identity. Se l'utente finale o uno dei gruppi di appartenenza è autorizzato ad accedere al documento, allora l'utente finale è autorizzato ad accedere al documento.

Esempio di RequestMetadata in formato JSON:

request_metadata: {
    user_info: {
        id: user:fake_user_id
    }
}

Oltre a seguire la guida Guida rapida, questa modalità di controllo dell'accesso#39;accesso richiede alcuni passaggi aggiuntivi prima di iniziare a inviare richieste a Document AI Warehouse:

  1. Integrati con Cloud Identity per gli utenti finali e i gruppi.
  2. Segui le istruzioni riportate nella sezione Configura il controllo dell'accesso per impostare un criterio di progetto predefinito. Puoi anche impostare un ACL a livello di documento per documenti specifici dopo la creazione.

Dopo aver completato i passaggi precedenti, puoi utilizzare l'account di servizio per effettuare chiamate API a Document AI Warehouse con le informazioni dell'utente finale nella sezione RequestMetadata del corpo della richiesta.

Configura il controllo dell'accesso

Prima di iniziare

Prima di iniziare, assicurati di aver completato la pagina Guida rapida.

SetAcl e FetchAcl

Quando viene creato un nuovo progetto, non viene impostata alcuna ACL del progetto. Il proprietario del progetto può chiamare l'API Document AI Warehouse SetAcl per impostare un criterio del progetto predefinito utilizzando ruoli predefiniti per il progetto impostando il campo projectOwner su true utilizzando il account di servizio. I membri delle norme del progetto hanno accesso a tutti i documenti del progetto a seconda dei ruoli concessi. Puoi concedere l'accesso agli utenti o ai gruppi amministrativi nel criterio del progetto predefinito.

Di seguito è riportata una tabella che riassume il ruolo richiesto per ogni azione sul documento. Per saperne di più sulle autorizzazioni concesse a ciascun ruolo, consulta Ruoli e autorizzazioni IAM.

Per effettuare chiamate all'API Document Schema utilizzando l'account di servizio, consulta projects.locations.documentSchemas.

Metodo API Document Ruoli obbligatori
CreateDocument roles/contentwarehouse.documentCreator
UpdateDocument roles/contentwarehouse.documentEditor
DeleteDocument
SetACL		 roles/contentwarehouse.documentAdmin
GetDocument
FetchACL
SearchDocuments		 roles/contentwarehouse.documentViewer

CreateDocument

Concedi all'utente finale o al gruppo l'accesso di Creator, se non è stato concesso:

  • [Facoltativo] Recupera i gruppi di appartenenza per l'amministratore utente finale dal servizio di identità del cliente. Questo passaggio può essere ignorato per i clienti che utilizzano Cloud Identity.
  • Concedi all'utente finale A (o al gruppo di cui fa parte l'utente A) il ruolo roles/contentwarehouse.documentCreator a livello di progetto effettuando la chiamata a SetAcl utilizzando il account di servizio con l'amministratore utente finale [e i gruppi di appartenenza] nei metadati della richiesta. L'amministratore utente finale ha accesso documentAdmin a livello di progetto.

Creare un documento:

  • (Facoltativo) Recupera i gruppi di appartenenza per l'utente finale A dal tuo servizio di identità. Questo passaggio può essere saltato se utilizzi Cloud Identity.
  • Chiama CreateDocument con l'utente finale A [e i gruppi di appartenenza] nei metadati della richiesta per creare un documento utilizzando l'account di servizio. Dopo la creazione del documento, l'utente finale A può visualizzarlo e modificarlo per impostazione predefinita. I clienti possono anche specificare una policy predefinita per concedere l'accesso a utenti o gruppi durante la creazione. Ad esempio, concedendo al gruppoX l'accesso documentViewer, al gruppoY l'accesso documentEditor e al gruppoZ l'accesso documentAdmin.

GetDocument e FetchAcl

Una volta creato il documento, l'utente finale A o i membri del gruppoX, del gruppoY o del gruppoZ possono chiamare GetDocument per visualizzare il documento o chiamare FetchAcl per visualizzare l'elenco di controllo dell'accesso del documento. Procedi nel seguente modo:

  1. (Facoltativo) Recupera i gruppi di appartenenza per l'utente finale A dal tuo servizio di identità. Questo passaggio può essere saltato se utilizzi Cloud Identity.
  2. Chiama GetDocument o FetchAcl utilizzando il account di servizio con l'utente finale A (e i gruppi di appartenenza) nei metadati della richiesta.

La chiamata dell'utente finale B viene rifiutata se B non è membro di groupX, groupY o groupZ.

UpdateDocument, DeleteDocument e SetAcl

Dopo la creazione del documento, solo l'utente finale A o i membri del gruppo Y o del gruppo Z possono chiamare UpdateDocument per aggiornare il documento; solo l'utente finale A o i membri del gruppo Z possono chiamare DeleteDocument per eliminare il documento o SetAcl per condividerlo con altri utenti finali o gruppi. Procedi nel seguente modo:

  1. (Facoltativo) Recupera i gruppi di appartenenza per l'utente finale A dal tuo servizio di identità. Questo passaggio può essere saltato se utilizzi Cloud Identity.
  2. Chiama UpdateDocument, DeleteDocument o SetAcl utilizzando l'account di servizio con l'utente finale A [e i gruppi di appartenenza] nei metadati della richiesta.

La chiamata dei membri del gruppo X verrà negata perché hanno solo accesso documentViewer al documento.

SearchDocuments

I documenti restituiti dipendono dai ruoli concessi all'utente finale. Ad esempio, per una query di ricerca vuota, verranno restituiti tutti i documenti del progetto se l'utente finale dispone dell'accesso documentViewer a livello di progetto. In caso contrario, vengono restituiti solo i documenti con autorizzazione contentwarehouse.documents.get per l'utente finale specificato.

Per effettuare una chiamata all'API SearchDocument, i clienti devono eseguire i seguenti passaggi.

  1. (Facoltativo) Recupera i gruppi di appartenenza per l'utente finale A dal tuo servizio di identità. Questo passaggio può essere saltato se utilizzi Cloud Identity.
  2. Chiama SearchDocument utilizzando l'account di servizio con l'utente finale A (e i gruppi di appartenenza) nei metadati della richiesta.
Metodo API Document Link Ruoli obbligatori
CreateDocumentLink Fonte: roles/contentwarehouse.documentEditor
Destinazione: roles/contentwarehouse.documentViewer
ListLinkedTargets
ListLinkedSources		 roles/contentwarehouse.documentViewer
DeleteDocumentLink Fonte: roles/contentwarehouse.documentEditor

Gli utenti finali possono collegare il documento doc1 e il documento doc2 se dispongono dell'autorizzazione contentwarehouse.documents.update per doc1 e contentwarehouse.documents.get per doc2.

ListLinkedTargets e ListLinkedSources

Gli utenti finali possono elencare solo i documenti di destinazione o di origine con autorizzazione contentwarehouse.documents.get.

Gli utenti finali possono eliminare i link se dispongono dell'autorizzazione contentwarehouse.documents.update sui documenti di origine.