Administra el control de acceso

En esta página, se proporciona una descripción general de cómo administrar el control de acceso para proyectos y documentos.

Descripción general del control de acceso a los datos

El control de acceso a los datos es una función clave de Document AI Warehouse. Controla quién tiene acceso a qué recurso en Document AI Warehouse y qué nivel de acceso tiene.

Las APIs de Document AI Warehouse se compilan en Google Cloud. Se usa HTTPS para garantizar la transmisión segura de datos por Internet. La autenticación y la autorización se aplican en las APIs de Document AI Warehouse para proteger el servicio y los datos del usuario en función de las identidades de Google.

Las APIs de Document AI Warehouse usan OAuth2 para la autenticación con una cuenta de usuario. Todos los métodos de la API requieren el alcance de OAuth https://www.googleapis.com/auth/cloud-platform.

Document AI Warehouse aplica el control de acceso para los datos de los clientes según Cloud IAM. Document AI Warehouse define un conjunto de roles y permisos asociados para que puedas restringir el acceso de diferentes usuarios a los datos almacenados en nuestro servicio. Para obtener más información, consulta la sección Roles y permisos de IAM.

Usa una cuenta de servicio para aplicar el control de acceso básico

Necesitas una cuenta de servicio con los permisos necesarios para acceder a la API de Document AI Warehouse. Si sigues el paso "Aprovisiona a través de la consola de Google Cloud " en la guía de inicio rápido, se aprovisionará automáticamente una cuenta de servicio con el rol de administrador de Document AI Warehouse.

Modo de control de acceso

Document AI Warehouse proporciona tres modos de control de acceso:

Acceso universal: Sin control de acceso a nivel de documento
Control de acceso a nivel de documento con tu propio servicio de identidad
Control de acceso a nivel de documento con Cloud Identity

Los usuarios deben elegir uno de los modos de acceso durante el proceso de aprovisionamiento. En las siguientes secciones, se describe la diferencia entre los tres modos de control de acceso y se muestra cómo habilitar cada uno de ellos.

Acceso universal

El control de acceso universal te permite usar solo Identity and Access Management (IAM) para administrar los permisos. IAM aplica los mismos permisos a todos los documentos del proyecto con la identidad autenticada.

En este modo, cuando termines el procedimiento de aprovisionamiento en la guía de inicio rápido, tú y todos tus usuarios podrán acceder a todos los documentos del proyecto Google Cloudseleccionado en el servicio de Document AI Warehouse con la cuenta de servicio y los permisos asociados a ella.

En el resto de este documento, se analiza el control de acceso a nivel del documento. Si utilizas el acceso universal, puedes omitir el resto del documento.

Control de acceso a nivel del documento

Si eres usuario de Document AI Warehouse, puedes hacer lo siguiente:

Trae tu propio servicio de identidad
- Tanto el usuario final como los grupos de membresía del usuario final son obligatorios en los metadatos de la solicitud. Si tu empresa tiene su propia forma de autenticar al usuario y de identificar a qué grupos pertenece, usa esta opción.
Usa Cloud Identity.
- Solo se requiere el usuario final en los metadatos de la solicitud, ya que Document AI Warehouse recopila los grupos de membresía de Cloud Identity para los clientes. La diferencia entre esto y el uso de un servicio de identidad personalizado es que administras las membresías de grupo del usuario con Cloud Identity en lugar de un sistema interno.

Existen algunas limitaciones para usar el modo de acceso a nivel del documento:

Solo se admiten miembros y roles en la ACL. Se ignoran las condiciones de IAM.
No se admiten roles personalizados en la ACL.
Document AI Warehouse no verifica las credenciales de los usuarios finales. Document AI Warehouse solo verifica las credenciales de la cuenta de servicio para asegurarse de que las llamadas provengan de los clientes. Las credenciales del usuario final deben verificarse del lado del cliente.
Los clientes deben proporcionar el usuario final (y todos los grupos de los que el usuario final sea miembro si no se usa la opción de Cloud Identity) en los metadatos de la solicitud para aplicar el control de acceso.
La cantidad de grupos de membresía para el usuario final debe ser inferior a 100.

Control de acceso a nivel de documento con el servicio de identidad propio del cliente

Puedes elegir este modo si quieres hacer lo siguiente:

Otorgar a los usuarios finales (grupos) diferentes permisos para acceder a cada uno de los documentos
Usa tu propio servicio de identidad.

Este modo te permite usar IAM y las listas de control de acceso (LCA) para administrar los permisos. Cada documento de Document AI Warehouse se puede configurar con una LCA específica a nivel del documento. La autenticación y la autorización se realizan de la siguiente manera:

La credencial de la cuenta de servicio se autentica y autoriza para acceder al servicio.
En los metadatos de la solicitud, incluye el usuario final y los grupos de membresía del usuario final. El usuario final o al menos uno de los grupos a los que pertenece el usuario final debe tener permiso para acceder al documento.

Document AI Warehouse otorga acceso al documento solicitado solo si se cumplen ambas condiciones de la lista anterior.

El UserInfo (incluidos el ID del usuario final y los IDs de los grupos de membresía del usuario) del RequestMetadata proporcionado en la llamada a la API se usa para validar si el usuario final tiene permiso para realizar la acción correspondiente en el recurso del documento solicitado. Por ejemplo, el UserInfo proporcionado en la API de GetDocument se usa para validar si el usuario final tiene permiso para ver el documento. Si el usuario final o uno de los grupos de membresía tiene permiso para ver el documento, el usuario final tiene permiso para ver el documento.

Ejemplo de RequestMetadata en 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,
        ]
    }
}

Además de seguir la guía de inicio rápido, este modo de control de acceso requiere algunos pasos adicionales antes de que comiences a enviar APIs a Document AI Warehouse:

Recupera las membresías de grupos de un usuario final determinado desde tu servicio de directorio (por ejemplo, Azure Active Directory o Okta).
Sigue las instrucciones de la sección Configura el control de acceso para establecer una política predeterminada del proyecto. También puedes establecer una LCA a nivel del documento para documentos específicos después de la creación.

Después de completar los pasos anteriores, ya puedes usar la cuenta de servicio para realizar llamadas a la API de Document AI Warehouse con información del usuario final y de la membresía del grupo en la sección RequestMetadata del cuerpo de la solicitud.

En este modo, debes implementar un proxy para autenticar y autorizar a los usuarios finales. El proxy usa la cuenta de servicio a la que se le otorgó el rol de administrador para acceder al servicio. La clave de la cuenta de servicio debe protegerse para que solo la use el proxy.

Como solución lista para usar, la consola de Document AI Warehouse es un proxy que puede almacenar la clave de la cuenta de servicio, autenticar a los usuarios finales a través de las identidades de Google y reenviar las solicitudes a Document AI Warehouse.

Control de acceso a nivel de documento con Cloud Identity

Como alternativa a usar tu propio servicio de identidad, también puedes habilitar Cloud Identity para simplificar el proceso.

Para administrar de forma centralizada los usuarios y grupos, Google Cloud los clientes puedenconfigurar Cloud Identity desde ceroo federar identidades entre Google y otros proveedores de identidad, comoActive DirectoryyAzure Active Directory.

La sección UserInfo de RequestMetadata proporcionada en la llamada a la API se usa para validar si el usuario final tiene permiso para realizar la acción correspondiente en el recurso del documento solicitado. Con Cloud Identity, solo se requiere el ID del usuario final en RequestMetadata, y Document AI Warehouse recopila la información del grupo de membresía del servicio de Cloud Identity. Si el usuario final o uno de los grupos de membresía tiene permiso para acceder al documento, el usuario final tendrá permiso para acceder al documento.

Ejemplo de RequestMetadata en formato JSON:

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

Además de seguir la guía de inicio rápido, este modo de control de acceso requiere algunos pasos adicionales antes de que comiences a enviar solicitudes a Document AI Warehouse:

Integración con Cloud Identity para los usuarios finales y los grupos
Sigue las instrucciones de la sección Configura el control de acceso para establecer una política predeterminada del proyecto. También puedes establecer una LCA a nivel del documento para documentos específicos después de la creación.

Después de completar los pasos anteriores, ya puedes usar la cuenta de servicio para realizar llamadas a la API de Document AI Warehouse con información del usuario final en la sección RequestMetadata del cuerpo de la solicitud.

Configura el control de acceso

Antes de comenzar

Antes de comenzar, asegúrate de haber completado la página de Inicio rápido.

SetAcl y FetchAcl

Cuando se crea un proyecto nuevo, no se establece ninguna LCA del proyecto. El propietario del proyecto puede llamar a la API de SetAcl de Document AI Warehouse para establecer una política del proyecto predeterminada con roles predefinidos para el proyecto. Para ello, debe establecer el campo projectOwner como verdadero con la cuenta de servicio. Los miembros de la política del proyecto tienen acceso a todos los documentos del proyecto según los roles otorgados. Puedes otorgar acceso a usuarios o grupos administradores en la política del proyecto predeterminada.

En la siguiente tabla, se resume el rol requerido para cada acción del documento. Para obtener más información sobre los permisos que se otorgan a cada rol, consulta Roles y permisos de IAM.

Para realizar llamadas a la API de Document Schema con la cuenta de servicio, consulta projects.locations.documentSchemas.

Método de la API de Document	Roles obligatorios
`CreateDocument`	`roles/contentwarehouse.documentCreator`
`UpdateDocument`	`roles/contentwarehouse.documentEditor`
`DeleteDocument` `SetACL`	`roles/contentwarehouse.documentAdmin`
`GetDocument` `FetchACL` `SearchDocuments`	`roles/contentwarehouse.documentViewer`

CreateDocument

Otorga acceso de creador al usuario final o al grupo si aún no lo tiene:

[Opcional] Recupera los grupos de membresía del administrador del usuario final desde el servicio de identidad del cliente. Los clientes que usan Cloud Identity pueden omitir este paso.
Otorga al usuario final A (o al grupo al que pertenece el usuario A) el rol roles/contentwarehouse.documentCreator a nivel del proyecto llamando a SetAcl con la cuenta de servicio con el administrador del usuario final [y los grupos de membresía] en los metadatos de la solicitud. El administrador del usuario final tiene acceso de documentAdmin a nivel del proyecto.

Crea un documento:

Opcional: Recupera los grupos de membresía del usuario final A desde tu servicio de identidad. Puedes omitir este paso si usas Cloud Identity.
Realiza la llamada a CreateDocument con el usuario final A [y los grupos de membresía] en los metadatos de la solicitud para crear un documento con la cuenta de servicio. Después de crear el documento, el usuario final A puede verlo y editarlo de forma predeterminada. Los clientes también pueden especificar una política predeterminada para otorgar acceso a usuarios o grupos durante la creación. Por ejemplo, otorgar al grupoX el acceso documentViewer, al grupoY el acceso documentEditor y al grupoZ el acceso documentAdmin.

GetDocument y FetchAcl

Después de crear el documento, el usuario final A o los miembros de los gruposX, Y o Z pueden llamar a GetDocument para ver el documento o llamar a FetchAcl para ver la ACL del documento. A continuación, se indican los pasos que debes seguir:

Opcional: Recupera los grupos de membresía del usuario final A desde tu servicio de identidad. Puedes omitir este paso si usas Cloud Identity.
Llama a GetDocument o FetchAcl con la cuenta de servicio del usuario final A (y los grupos de membresía) en los metadatos de la solicitud.

Se rechaza la llamada del usuario final B si B no es miembro de groupX, groupY o groupZ.

UpdateDocument, DeleteDocument y SetAcl

Después de crear el documento, solo el usuario final A o los miembros del grupoY o del grupoZ pueden llamar a UpdateDocument para actualizar el documento; solo el usuario final A o los miembros del grupoZ pueden llamar a DeleteDocument para borrar el documento o a SetAcl para compartir el documento con otros usuarios finales o grupos. A continuación, se indican los pasos que debes seguir:

Opcional: Recupera los grupos de membresía del usuario final A desde tu servicio de identidad. Puedes omitir este paso si usas Cloud Identity.
Llama a UpdateDocument, DeleteDocument o SetAcl con la cuenta de servicio con el usuario final A [y los grupos de membresía] en los metadatos de la solicitud.

Se rechazará la llamada de los miembros de groupX porque solo tienen acceso de documentViewer al documento.

SearchDocuments

Los documentos que se muestran dependen de los roles otorgados al usuario final. Por ejemplo, para una búsqueda vacía, se devolverán todos los documentos del proyecto si el usuario final tiene acceso de documentViewer a nivel del proyecto. De lo contrario, solo se devuelven los documentos con permiso contentwarehouse.documents.get para el usuario final determinado.

Para realizar una llamada a la API de SearchDocument, los clientes deben seguir estos pasos.

Opcional: Recupera los grupos de membresía del usuario final A desde tu servicio de identidad. Puedes omitir este paso si usas Cloud Identity.
Realiza la llamada a SearchDocument con la cuenta de servicio del usuario final A (y los grupos de membresía) en los metadatos de la solicitud.

APIs de Document Link

Método de la API de Document Link	Roles obligatorios
`CreateDocumentLink`	Fuente: `roles/contentwarehouse.documentEditor` Destino: `roles/contentwarehouse.documentViewer`
`ListLinkedTargets` `ListLinkedSources`	`roles/contentwarehouse.documentViewer`
`DeleteDocumentLink`	Fuente: `roles/contentwarehouse.documentEditor`

CreateDocumentLink

Los usuarios finales pueden vincular el documento doc1 y el documento doc2 si tienen permiso de contentwarehouse.documents.update para doc1 y permiso de contentwarehouse.documents.get para doc2.

ListLinkedTargets y ListLinkedSources

Los usuarios finales solo pueden enumerar los documentos de destino o fuente con permiso de contentwarehouse.documents.get.

DeleteDocumentLink

Los usuarios finales pueden borrar los vínculos si tienen permiso de contentwarehouse.documents.update en los documentos fuente.