Gerenciar o controle de acesso

Cuidado: o Document AI Warehouse foi descontinuado e não estará mais disponível no Google Cloud após 16 de janeiro de 2025. Para proteger seus dados, migre todos os documentos salvos no Document AI Warehouse para uma alternativa como o Cloud Storage. Verifique se a migração de dados foi concluída antes da data de descontinuação para evitar a perda de dados. Consulte Descontinuações para mais detalhes.

Nesta página, você encontra uma visão geral de como gerenciar o controle de acesso para projetos e documentos.

Visão geral do controle de acesso aos dados

O controle de acesso a dados é um recurso fundamental do Document AI Warehouse. Ele controla quem tem acesso a qual recurso no Document AI Warehouse e o nível de acesso.

As APIs do Document AI Warehouse são criadas com base no Google Cloud. O HTTPS é usado para garantir a transmissão segura de dados pela Internet. A autenticação e a autorização são aplicadas nas APIs do Document AI Warehouse para proteger o serviço e os dados do usuário com base nas identidades do Google.

As APIs do Document AI Warehouse usam o OAuth2 para autenticação com uma conta de usuário. Todos os métodos de API exigem o escopo do OAuth https://www.googleapis.com/auth/cloud-platform.

O Document AI Warehouse aplica o controle de acesso aos dados do cliente com base no Cloud IAM. O Document AI Warehouse define um conjunto de funções e permissões associadas para restringir o acesso de diferentes usuários aos dados armazenados no nosso serviço. Para mais informações, consulte a seção Papéis e permissões do IAM.

Usar uma conta de serviço para aplicar o controle de acesso básico

Você precisa de uma conta de serviço com as permissões necessárias para acessar a API Document AI Warehouse. Se você seguir a etapa "Provisionar pelo console Google Cloud " no guia de início rápido, uma conta de serviço será provisionada automaticamente com a função de administrador do Document AI Warehouse.

Observação: se você escolher o modelo de acesso universal, conforme descrito na seção a seguir, essa conta de serviço é tudo o que você precisa para acessar o serviço Document AI Warehouse. Caso contrário, você também precisará transmitir o controle de acesso no nível do documento com base nas identidades declaradas na solicitação.

Modo de controle de acesso

O Document AI Warehouse oferece três modos de controle de acesso:

• Acesso universal: sem controle de acesso no nível do documento
• Controle de acesso no nível do documento com seu próprio serviço de identidade
• Controle de acesso no nível do documento com o Cloud Identity

Os usuários precisam escolher um dos modos de acesso durante o processo de provisionamento. As seções a seguir descrevem a diferença entre os três modos de controle de acesso e mostram como ativar cada um deles.

Acesso universal

Com o controle de acesso universal, você usa apenas o Identity and Access Management (IAM) para gerenciar permissões. O IAM aplica as mesmas permissões a todos os documentos no projeto com a identidade autenticada.

Nesse modo, quando você concluir o procedimento de provisionamento no guia de início rápido, você e todos os seus usuários poderão acessar todos os documentos no projeto Google Cloud selecionado no serviço Document AI Warehouse usando a conta de serviço, com as permissões associadas a ela.

O restante deste documento discute o controle de acesso no nível do documento. Se você estiver usando o acesso universal, ignore o restante do documento.

Controle de acesso no nível do documento

Para usuários do Document AI Warehouse, você pode:

• Use seu próprio serviço de identidade
  • O usuário final e os grupos de associação de usuários finais são obrigatórios nos metadados da solicitação. Use essa opção se sua empresa tiver uma maneira própria de autenticar o usuário e identificar a quais grupos ele pertence.
• Use o Cloud Identity
  • Apenas o usuário final é necessário nos metadados da solicitação porque o Document AI Warehouse coleta os grupos de associação do Cloud Identity para os clientes. A diferença entre isso e usar um serviço de identidade personalizado é que você gerencia as associações de grupo do usuário usando o Cloud Identity em vez de um sistema interno.

Há algumas limitações ao usar o modo de acesso no nível do documento:

• Apenas membros e papéis na ACL são aceitos. As condições do IAM são ignoradas.
• Não há suporte para papéis personalizados na ACL.
• O Document AI Warehouse não verifica as credenciais do usuário final. O Document AI Warehouse verifica apenas as credenciais da conta de serviço para garantir que as chamadas sejam dos clientes. As credenciais do usuário final precisam ser verificadas pelo cliente.
• Os clientes precisam fornecer o usuário final (e todos os grupos de que ele faz parte, se não estiver usando a opção do Cloud Identity) nos metadados da solicitação para aplicar o controle de acesso.
• O número de grupos de assinatura para o usuário final precisa ser menor que 100.

Controle de acesso no nível do documento com o serviço de identidade do cliente

Escolha esse modo se quiser fazer o seguinte:

• Conceda aos usuários finais (grupos) permissões diferentes para acessar cada um dos documentos.
• Use seu próprio serviço de identidade.

Esse modo permite usar o IAM e as listas de controle de acesso (ACLs) para gerenciar permissões. Cada documento no Document AI Warehouse pode ser configurado com uma ACL no nível do documento específica. A autenticação e a autorização acontecem da seguinte maneira:

• A credencial da conta de serviço é autenticada e autorizada a acessar o serviço.
• Nos metadados da solicitação, inclua o usuário final e os grupos de associação dele. O usuário final ou pelo menos um dos grupos a que ele pertence precisa ter permissão para acessar o documento.

O Document AI Warehouse concede acesso ao documento solicitado somente se as duas condições na lista anterior forem atendidas.

O UserInfo (incluindo ID do usuário final e IDs do grupo de associação do usuário) do RequestMetadata fornecido na chamada de API é usado para validar se o usuário final tem permissão para realizar a ação correspondente no recurso de documento solicitado. Por exemplo, o UserInfo fornecido na API GetDocument é usado para validar se o usuário final tem permissão para acessar o documento. Se o usuário final ou um dos grupos de associação tiver permissão para acessar o documento, o usuário final também terá.

Exemplo de RequestMetadata no 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,
        ]
    }
}

Além de seguir o guia de início rápido, esse modo de controle de acesso exige algumas etapas extras antes de começar a enviar APIs para o Document AI Warehouse:

1. Extraia as associações a grupos de um determinado usuário final do seu serviço de diretório (por exemplo, Azure Active Directory ou Okta).
2. Siga as instruções na seção Configurar controle de acesso para definir uma política padrão do projeto. Também é possível definir uma ACL no nível do documento para arquivos específicos após a criação.

Depois de concluir as etapas anteriores, você poderá usar a conta de serviço para fazer chamadas de API ao Document AI Warehouse com informações de usuário final e de associação a grupos na seção RequestMetadata do corpo da solicitação.

Nesse modo, você precisa implantar um proxy para autenticar e autorizar os usuários finais. O proxy usa a conta de serviço com a função de administrador para acessar o serviço. A chave da conta de serviço precisa ser protegida para que seja usada apenas pelo proxy.

Como uma solução pronta para uso, o console do Document AI Warehouse é um proxy que pode armazenar a chave da conta de serviço, autenticar os usuários finais pelas identidades do Google e encaminhar as solicitações para o Document AI Warehouse.

Controle de acesso no nível do documento com o Cloud Identity

Como alternativa ao uso do seu próprio serviço de identidade, você também pode ativar o uso do Cloud Identity para simplificar o processo.

Para gerenciar usuários e grupos de forma centralizada,os clientes do Google Cloud podem configurar o Cloud Identity do zero ou federar identidades entre o Google e outros provedores de identidade, como o Active Directory e o Azure Active Directory.

A seção UserInfo de RequestMetadata fornecida na chamada de API é usada para validar se o usuário final tem permissão para realizar a ação correspondente no recurso de documento solicitado. Com o Cloud Identity, apenas o ID do usuário final é necessário no RequestMetadata, e o Document AI Warehouse coleta as informações do grupo de associação do serviço do Cloud Identity. Se o usuário final ou um dos grupos de associação tiver permissão para acessar o documento, o usuário final terá permissão para acessar o documento.

Exemplo de RequestMetadata no formato JSON:

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

Além de seguir o guia de início rápido, esse modo de controle de acesso exige algumas etapas adicionais antes de começar a enviar solicitações ao Document AI Warehouse:

1. Integre com o Cloud Identity para os usuários finais e grupos.
2. Siga as instruções na seção Configurar controle de acesso para definir uma política padrão do projeto. Também é possível definir uma ACL no nível do documento para arquivos específicos após a criação.

Depois de concluir as etapas anteriores, você poderá usar a conta de serviço para fazer chamadas de API ao Document AI Warehouse com informações do usuário final na seção RequestMetadata do corpo da solicitação.

Configurar o controle de acesso

Antes de começar

Antes de começar, confira se você concluiu a página de início rápido.

Observação: esta página só é relevante se você estiver usando o controle de acesso no nível do documento no seu projeto. Se você escolheu o controle de acesso universal para seu projeto, pode pular o restante deste documento.

SetAcl e FetchAcl

Quando um novo projeto é criado, nenhuma ACL é definida. O proprietário do projeto pode chamar a API Document AI Warehouse SetAcl para definir uma política do projeto padrão usando papéis predefinidos para o projeto definindo o campo projectOwner como "true" usando a conta de serviço. Os membros da política do projeto têm acesso a todos os documentos do projeto, dependendo dos papéis concedidos. É possível conceder acesso a usuários ou grupos administradores na política padrão do projeto.

Observação: chamar SetAcl substitui a ACL atual do projeto ou documento. Para evitar que a configuração de ACL salva anteriormente seja substituída, chame FetchAcl para receber a ACL atual do projeto ou documento primeiro e inclua-a como parte da solicitação SetAcl.

A tabela a seguir resume a função necessária para cada ação de documento. Para mais informações sobre as permissões concedidas a cada papel, consulte Papéis e permissões do IAM.

Para fazer chamadas à API Document Schema usando a conta de serviço, consulte projects.locations.documentSchemas.

Método da API Document	Funções exigidas
CreateDocument	roles/contentwarehouse.documentCreator
UpdateDocument	roles/contentwarehouse.documentEditor
DeleteDocument SetACL	roles/contentwarehouse.documentAdmin
GetDocument FetchACL SearchDocuments	roles/contentwarehouse.documentViewer

CreateDocument

Conceda ao usuário final ou ao grupo acesso de criador, se ainda não tiver sido concedido:

• [Opcional] Busque grupos de associação para o administrador do usuário final no serviço de identidade do cliente. Essa etapa pode ser ignorada por clientes que usam o Cloud Identity.
• Conceda ao usuário final A (ou ao grupo de que ele faz parte) o papel roles/contentwarehouse.documentCreator no nível do projeto fazendo a chamada para SetAcl usando a conta de serviço com o administrador do usuário final [e grupos de associação] nos metadados da solicitação. O administrador do usuário final tem acesso documentAdmin no nível do projeto.

Criar um documento:

• Opcional: busque os grupos de associação do usuário final A no seu serviço de identidade. Essa etapa pode ser ignorada se você usa o Cloud Identity.
• Faça a chamada para CreateDocument com o usuário final A [e grupos de associação] nos metadados da solicitação para criar um documento usando a conta de serviço. Depois que o documento é criado, o usuário final A pode visualizar e editar o documento por padrão. Os clientes também podem especificar uma política padrão para conceder acesso a usuários ou grupos durante a criação. Por exemplo, conceder ao grupoX o acesso documentViewer, ao grupoY o acesso documentEditor e ao grupoZ o acesso documentAdmin.

Observação: o papel padrão de criador de documentos concedido pode ser configurado na configuração do projeto. Pode ser documentAdmin, documentEditor ou documentViewer. Se não estiver definido, o criador do documento vai receber a função documentAdmin por padrão.

GetDocument e FetchAcl

Depois que o documento for criado, o usuário final A ou os membros dos grupos X, Y ou Z poderão chamar GetDocument para ver o documento ou FetchAcl para ver a ACL dele. Estas são as etapas:

1. Opcional: busque os grupos de associação do usuário final A no seu serviço de identidade. Essa etapa pode ser ignorada se você usa o Cloud Identity.
2. Faça a chamada para GetDocument ou FetchAcl usando a conta de serviço com o usuário final A (e grupos de associação) nos metadados da solicitação.

A chamada do usuário final B será rejeitada se B não for um participante do grupoX, grupoY ou grupoZ.

UpdateDocument, DeleteDocument e SetAcl

Depois que o documento é criado, apenas o usuário final A ou os membros do grupoY ou grupoZ podem chamar UpdateDocument para atualizar o documento. Somente o usuário final A ou os membros do grupoZ podem chamar DeleteDocument para excluir o documento ou SetAcl para compartilhar o documento com outros usuários finais ou grupos. Estas são as etapas:

1. Opcional: busque os grupos de associação do usuário final A no seu serviço de identidade. Essa etapa pode ser ignorada se você usa o Cloud Identity.
2. Faça a chamada para UpdateDocument, DeleteDocument ou SetAcl usando a conta de serviço com o usuário final A [e grupos de associação] nos metadados da solicitação.

A chamada dos membros do grupoX será negada porque eles só têm acesso de documentViewer ao documento.

SearchDocuments

Os documentos retornados dependem das funções concedidas ao usuário final. Por exemplo, para uma consulta de pesquisa vazia, todos os documentos do projeto serão retornados se o usuário final tiver acesso documentViewer no nível do projeto. Caso contrário, somente os documentos com permissão contentwarehouse.documents.get para o usuário final especificado serão retornados.

Para fazer uma chamada à API SearchDocument, os clientes precisam seguir estas etapas.

1. Opcional: busque os grupos de associação do usuário final A no seu serviço de identidade. Essa etapa pode ser ignorada se você usa o Cloud Identity.
2. Faça a chamada para SearchDocument usando a conta de serviço com o usuário final A (e grupos de associação) nos metadados da solicitação.

APIs de link de documentos

Método da API Document Link	Funções exigidas
CreateDocumentLink	Origem: roles/contentwarehouse.documentEditor Destino: roles/contentwarehouse.documentViewer
ListLinkedTargets ListLinkedSources	roles/contentwarehouse.documentViewer
DeleteDocumentLink	Fonte: roles/contentwarehouse.documentEditor

CreateDocumentLink

Os usuários finais podem vincular os documentos doc1 e doc2 se tiverem permissão contentwarehouse.documents.update para doc1 e contentwarehouse.documents.get para doc2.

ListLinkedTargets e ListLinkedSources

Os usuários finais só podem listar os documentos destino ou origem com a permissão contentwarehouse.documents.get.

DeleteDocumentLink

Os usuários finais podem excluir os links se tiverem permissão de contentwarehouse.documents.update nos documentos de origem.