管理访问权限控制

本页面简要介绍了如何管理项目和文档的访问权限控制。

数据访问权限控制概览

数据访问权限控制是 Document AI Warehouse 的一项关键功能。它用于控制哪些用户有权访问 Document AI Warehouse 中的哪些资源，以及他们拥有何种级别的访问权限。

Document AI Warehouse API 基于 Google Cloud 构建。HTTPS 用于确保通过互联网安全地传输数据。Document AI Warehouse API 会强制执行身份验证和授权，以根据 Google 身份保护服务和用户数据。

Document AI Warehouse API 使用 OAuth2 对用户账号进行身份验证。所有 API 方法都需要 https://www.googleapis.com/auth/cloud-platform OAuth 范围。

Document AI Warehouse 会根据 Cloud IAM 对客户数据强制执行访问权限控制。Document AI Warehouse 定义了一组角色和相关权限，以便您限制不同用户对存储在我们服务中的数据的访问权限。如需了解详情，请参阅 IAM 角色和权限部分。

使用服务账号强制执行基本访问权限控制

您需要一个服务账号，并向其授予访问 Document AI Warehouse API 所需的权限。如果您按照快速入门指南中的“通过 Google Cloud 控制台进行配置”步骤操作，系统会自动配置一个具有 Document AI Warehouse 管理员角色的服务账号。

访问权限控制模式

Document AI Warehouse 提供三种访问权限控制模式：

公开访问权限：不进行文档级访问权限控制
针对自有身份服务的用户实施文档级访问权限控制
通过 Cloud Identity 实施文档级访问权限控制

用户需要在配置过程中选择一种访问模式。以下部分概述了这三种访问权限控制模式之间的区别，并演示了如何启用每种模式。

通用访问机制

借助通用访问权限控制，您只需使用 Identity and Access Management (IAM) 即可管理权限。IAM 会将相同的权限应用于项目中具有已验证身份的所有文档。

在此模式下，当您完成快速入门指南中的配置程序后，您和所有用户都可以使用服务账号访问 Document AI Warehouse 服务中选定 Google Cloud项目下的所有文档，并拥有与该服务账号关联的权限。

本文档的其余部分将讨论文档级访问权限控制。如果您使用的是公开访问权限，可以跳过本文档的其余部分。

文档级访问权限控制

对于 Document AI Warehouse 用户，您可以执行以下任一操作：

自带身份服务
- 请求元数据中必须包含最终用户和最终用户组成员群组。如果贵公司有自己的用户身份验证方式，并且可以确定用户所属的群组，请使用此选项。
使用 Cloud Identity
- 由于 Document AI Warehouse 会从 Cloud Identity 中收集客户的成员组，因此请求元数据中只需要最终用户。此方法与使用自定义身份服务的区别在于，您可以使用 Cloud Identity 而不是内部系统来管理用户的群组成员资格。

使用文档级访问模式存在一些限制：

仅支持 ACL 中的成员和角色。系统会忽略 IAM 条件。
ACL 中不支持自定义角色。
Document AI Warehouse 不会验证最终用户凭据。Document AI Warehouse 仅验证服务账号凭据，以确保调用来自客户。最终用户凭据需要在客户侧进行验证。
客户需要在请求元数据中提供最终用户（以及最终用户所属的所有群组，如果未使用 Cloud Identity 选项），以便强制执行访问权限控制。
最终用户的会员组数量应少于 100 个。

针对客户自有身份服务的用户实施文档级访问权限控制

如果您想执行以下操作，可以选择此模式：

向最终用户（群组）授予不同的权限，以便其访问每个文档。
使用您自己的身份服务。

在此模式下，您可以将 IAM 和访问控制列表 (ACL) 一起使用来管理权限。Document AI Warehouse 中的每个文档都可以配置特定的文档级 ACL。身份验证和授权过程如下：

服务账号凭据经过身份验证和授权，可以访问相应服务。
在请求元数据中，包含最终用户和最终用户组成员身份。最终用户或最终用户所属的至少一个群组需要拥有访问相应文档的权限。

只有满足上述列表中的两个条件时，Document AI Warehouse 才会授予对所请求文档的访问权限。

API 调用中提供的 RequestMetadata 的 UserInfo（包括最终用户 ID 和用户成员资格组 ID）用于验证最终用户是否获准针对所请求的文档资源执行相应操作。例如，GetDocument API 中提供的 UserInfo 用于验证最终用户是否有权查看相应文档。如果最终用户或某个成员群组有权查看文档，则最终用户有权查看该文档。

JSON 格式的 RequestMetadata 示例：

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,
        ]
    }
}

除了遵循快速入门指南之外，此访问权限控制模式还需要您在开始向 Document AI Warehouse 发送 API 之前完成一些额外的步骤：

从目录服务（例如 Azure Active Directory 或 Okta）中提取指定最终用户的群组成员资格。
按照配置访问权限控制部分中的说明设置默认项目政策。您还可以在创建特定文档后为其设置文档级 ACL。

完成上述步骤后，您现在可以使用服务账号向 Document AI Warehouse 发出 API 调用，并在请求正文的 RequestMetadata 部分中包含最终用户和群组成员身份信息。

在此模式下，您应部署代理来对最终用户进行身份验证和授权。代理使用被授予管理员角色的服务账号来访问服务。应保护服务账号密钥，使其仅供代理使用。

作为一种开箱即用的解决方案，Document AI Warehouse 控制台是一个代理，可以存储服务账号密钥、通过 Google 身份验证最终用户，并将请求转发给 Document AI Warehouse。

通过 Cloud Identity 实施文档级访问权限控制

除了使用自己的身份服务之外，您还可以选择使用 Cloud Identity 来简化流程。

为了集中管理用户和群组， Google Cloud 客户可以从头开始设置 Cloud Identity，也可以在 Google 与其他身份提供商（如 Active Directory 和 Azure Active Directory）之间联合身份。

API 调用中提供的 RequestMetadata 的 UserInfo 部分用于验证最终用户是否获准对所请求的文档资源执行相应操作。使用 Cloud Identity 时，RequestMetadata 中仅需提供最终用户 ID，Document AI Warehouse 会从 Cloud Identity 服务中收集成员资格群组信息。如果最终用户或某个成员群组有权访问相应文档，则最终用户有权访问该文档。

JSON 格式的 RequestMetadata 示例：

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

除了遵循快速入门指南之外，此访问权限控制模式还需要您在开始向 Document AI Warehouse 发送请求之前完成一些额外的步骤：

与面向最终用户和群组的 Cloud Identity 集成。
按照配置访问权限控制部分中的说明设置默认项目政策。您还可以在创建特定文档后为其设置文档级 ACL。

完成上述步骤后，您现在可以使用服务账号向 Document AI Warehouse 发出 API 调用，并在请求正文的 RequestMetadata 部分中包含最终用户信息。

配置访问权限控制

准备工作

在开始之前，请确保您已完成快速入门页面中的步骤。

SetAcl 和 FetchAcl

创建新项目时，系统不会设置任何项目 ACL。项目所有者可以调用 Document AI Warehouse SetAcl API，通过使用服务账号将 projectOwner 字段设置为 true，为项目设置使用预定义角色的默认项目政策。项目政策中的成员可以访问项目下的所有文档，具体取决于授予的角色。您可以在默认项目政策中向管理员用户或群组授予此访问权限。

下表总结了每项文档操作所需的角色。如需详细了解每个角色获得的权限，请参阅 IAM 角色和权限。

如需使用服务账号调用 Document Schema API，请参阅 projects.locations.documentSchemas。

记录 API 方法	所需的角色
`CreateDocument`	`roles/contentwarehouse.documentCreator`
`UpdateDocument`	`roles/contentwarehouse.documentEditor`
`DeleteDocument` `SetACL`	`roles/contentwarehouse.documentAdmin`
`GetDocument` `FetchACL` `SearchDocuments`	`roles/contentwarehouse.documentViewer`

CreateDocument

如果尚未授予最终用户或群组创建者访问权限，请授予：

[可选] 从客户的身份服务中获取最终用户管理员的成员资格群组。使用 Cloud Identity 的客户可以跳过此步骤。
通过调用 SetAcl，在请求元数据中使用具有最终用户管理员 [和会员群组] 权限的服务账号，在项目级层向最终用户 A（或用户 A 所属的群组）授予角色 roles/contentwarehouse.documentCreator。最终用户管理员在项目级层拥有 documentAdmin 访问权限。

创建文档：

可选：从您的身份服务中提取最终用户 A 的成员资格群组。如果您使用 Cloud Identity，则可以跳过此步骤。
在请求元数据中包含最终用户 A [和会员群组]，并调用 CreateDocument 以使用服务账号创建文档。创建文档后，最终用户 A 默认可以查看和修改该文档。客户还可以指定默认政策，以便在创建时向用户或群组授予访问权限。例如，向 groupX 授予 documentViewer 访问权限，向 groupY 授予 documentEditor 访问权限，并向 groupZ 授予 documentAdmin 访问权限。

GetDocument 和 FetchAcl

创建文档后，最终用户 A 或群组 X、群组 Y 或群组 Z 的成员可以调用 GetDocument 查看文档，也可以调用 FetchAcl 查看文档的 ACL。具体步骤如下所示：

可选：从您的身份服务中提取最终用户 A 的成员资格群组。如果您使用 Cloud Identity，则可以跳过此步骤。
使用最终用户 A（以及会员群组）的服务账号在请求元数据中调用 GetDocument 或 FetchAcl。

如果最终用户 B 不是 groupX、groupY 或 groupZ 的成员，则来自最终用户 B 的呼叫会被拒绝。

UpdateDocument、DeleteDocument 和 SetAcl

创建文档后，只有最终用户 A 或 groupY/groupZ 的成员可以调用 UpdateDocument 来更新文档；只有最终用户 A 或 groupZ 的成员可以调用 DeleteDocument 来删除文档，或调用 SetAcl 来与其他最终用户或群组共享文档。具体步骤如下所示：

可选：从您的身份服务中提取最终用户 A 的成员资格群组。如果您使用 Cloud Identity，则可以跳过此步骤。
使用最终用户 A [和会员群组] 的服务账号在请求元数据中调用 UpdateDocument、DeleteDocument 或 SetAcl。

来自 groupX 成员的调用将被拒绝，因为他们仅拥有对文档的 documentViewer 访问权限。

SearchDocuments

返回的文档取决于授予最终用户的角色。例如，对于空搜索查询，如果最终用户在项目级层拥有 documentViewer 访问权限，则系统将返回该项目下的所有文档。否则，系统只会返回给定最终用户拥有 contentwarehouse.documents.get 权限的文档。

如需调用 SearchDocument API，客户需要执行以下步骤。

可选：从您的身份服务中提取最终用户 A 的成员资格群组。如果您使用 Cloud Identity，则可以跳过此步骤。
使用服务账号调用 SearchDocument，并在请求元数据中包含最终用户 A（以及成员组）。

文档链接 API

Document Link API 方法	所需的角色
`CreateDocumentLink`	来源： `roles/contentwarehouse.documentEditor` 目标： `roles/contentwarehouse.documentViewer`
`ListLinkedTargets` `ListLinkedSources`	`roles/contentwarehouse.documentViewer`
`DeleteDocumentLink`	来源： `roles/contentwarehouse.documentEditor`

CreateDocumentLink

如果最终用户对文档 doc1 具有 contentwarehouse.documents.update 权限，对文档 doc2 具有 contentwarehouse.documents.get 权限，则最终用户可以关联文档 doc1 和文档 doc2。

ListLinkedTargets 和 ListLinkedSources

最终用户只能列出具有 contentwarehouse.documents.get 权限的目标或源文档。

DeleteDocumentLink

如果最终用户对源文档拥有 contentwarehouse.documents.update 权限，则可以删除链接。