管理存取控管

本頁面提供專案和文件存取權控管的總覽。

資料存取權控管總覽

資料存取權控管是 Document AI 倉儲的重要功能。可控管使用者在 Document AI 倉儲中可存取的資源，以及存取層級。

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 倉儲會根據 Cloud IAM，強制執行客戶資料的存取權控管。Document AI Warehouse 定義了一組角色和相關聯的權限，可供您限制不同使用者存取服務中儲存的資料。詳情請參閱「IAM 角色和權限」一節。

使用服務帳戶強制執行基本存取控管

您需要服務帳戶，並授予存取 Document AI Warehouse API 的必要權限。如果您按照「透過 Google Cloud 控制台佈建」步驟操作快速入門指南，系統會自動佈建服務帳戶，並指派 Document AI Warehouse 管理員角色。

存取權控管模式

Document AI 倉儲提供三種存取控管模式：

通用存取權：不設定文件層級的存取控管機制
透過自有身分服務，對使用者設定文件層級的存取控管機制
透過 Cloud Identity 設定文件層級的存取控管機制

使用者必須在佈建程序中選擇其中一種存取模式。以下各節將說明這三種存取控制模式的差異，並示範如何啟用每種模式。

通用存取權

通用存取權控管功能可讓您單獨使用 Identity and Access Management (IAM) 管理權限。IAM 會對專案中所有文件套用相同的權限，並使用已驗證的身分。

在這個模式下，當您完成快速入門指南中的佈建程序後，您和所有使用者就能使用服務帳戶，存取所選 Google Cloud專案中 Document AI Warehouse 服務的所有文件，並享有與服務帳戶相關聯的權限。

本文的其餘部分會說明文件層級的存取控管機制。如果您使用通用存取權，可以略過本文其餘內容。

文件層級存取權控管

Document AI 倉儲使用者可以採取下列其中一種做法：

自備身分識別服務
- 要求中繼資料必須包含使用者和使用者成員群組。如果貴公司有自己的使用者驗證方式，並可識別使用者所屬群組，請使用這個選項。
使用 Cloud Identity
- 要求中繼資料只需要使用者，因為 Document AI 倉儲會為客戶從 Cloud Identity 收集成員群組。與使用自訂身分識別服務不同的是，您可以使用 Cloud Identity 管理使用者群組成員資格，而非內部系統。

使用文件層級存取模式時，請注意以下限制：

僅支援 ACL 中的成員和角色。IAM 條件會遭到忽略。
存取控制清單不支援自訂角色。
Document AI 倉儲不會驗證使用者憑證，Document AI 倉儲只會驗證服務帳戶憑證，確保呼叫來自客戶。使用者憑證必須在客戶端完成驗證。
客戶必須在要求中提供使用者 (以及使用者所屬的所有群組，如果未使用 Cloud Identity 選項)，才能強制執行存取權控管。
終端使用者的成員群組數量應少於 100 個。

透過客戶自己的身分服務，對使用者設定文件層級的存取控管機制

如果您想執行下列操作，可以選擇這個模式：

授予使用者 (群組) 不同的權限，以存取各個文件。
使用您自己的身分識別服務。

這個模式可讓您同時使用 IAM 和存取控制清單 (ACL) 管理權限。Document AI 倉儲中的每份文件都可以設定專屬的「文件層級 ACL」。驗證和授權程序如下：

服務帳戶憑證已通過驗證，並獲得存取服務的授權。
在要求中繼資料中，加入使用者和使用者成員群組。使用者本人或所屬群組中至少一人，必須具備文件存取權。

只有在滿足上述清單中的兩個條件時，Document AI 倉儲才會授予所要求文件的存取權。

API 呼叫中提供的 UserInfo (包括使用者 ID 和使用者成員群組 ID) 會用於驗證使用者是否可對所要求的文件資源執行相應動作。RequestMetadata舉例來說，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,
        ]
    }
}

除了按照快速入門指南操作之外，如要使用這個存取權控管模式，您還需要完成幾個額外步驟，才能開始將 API 傳送至 Document AI 倉儲：

從目錄服務 (例如 Azure Active Directory 或 Okta) 擷取特定使用者的群組成員資格。
請按照「設定存取權控管」一節的說明，設定預設專案政策。您也可以在建立文件後，為特定文件設定文件層級的 ACL。

完成上述步驟後，您現在可以使用服務帳戶，在要求主體的 RequestMetadata 區段中，透過 API 呼叫 Document AI Warehouse，並提供使用者和群組成員資格資訊。

在這個模式中，您應部署 Proxy 來驗證及授權使用者。Proxy 會使用獲派管理員角色的服務帳戶存取服務。服務帳戶金鑰應受到保護，只能由 Proxy 使用。

Document AI Warehouse 主控台是現成解決方案，可做為 Proxy 儲存服務帳戶金鑰、透過 Google 身分驗證使用者，並將要求轉送至 Document AI Warehouse。

透過 Cloud Identity 設定文件層級的存取控管機制

除了使用自己的身分識別服務，您也可以選擇使用 Cloud Identity，簡化程序。

如要集中管理使用者和群組，客戶可以 Google Cloud 從頭設定 Cloud Identity，或在 Google 與其他身分識別提供者 (例如 Active Directory 和 Azure Active Directory) 之間連結身分識別。

API 呼叫中提供的 UserInfo 部分 RequestMetadata 用於驗證使用者是否可對所要求的文件資源執行相應動作。使用 Cloud Identity 時，RequestMetadata 中只需要使用者 ID，Document AI 倉儲會從 Cloud Identity 服務收集成員群組資訊。如果使用者或其中一個成員群組有權存取文件，使用者就能存取文件。

JSON 格式的範例 RequestMetadata：

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

除了按照快速入門指南操作，如要使用這個存取權控管模式，還必須先完成幾個額外步驟，才能開始將要求傳送至 Document AI 倉儲：

與Cloud Identity 整合，方便使用者和群組存取。
請按照「設定存取權控管」一節的說明，設定預設專案政策。您也可以在建立文件後，為特定文件設定文件層級的 ACL。

完成上述步驟後，您現在可以使用服務帳戶，在要求主體的 RequestMetadata 區段中加入使用者資訊，向 Document AI Warehouse 發出 API 呼叫。

設定存取控管機制

事前準備

開始前，請先完成快速入門頁面。

SetAcl 和 FetchAcl

建立新專案時，系統不會設定專案 ACL。專案擁有者可以呼叫 Document AI Warehouse SetAcl API，使用專案的預先定義角色，透過服務帳戶將 projectOwner 欄位設為 true，設定專案的預設政策。專案政策中的成員可存取專案中的所有文件，具體取決於授予的角色。您可以在預設專案政策中授予管理員使用者或群組存取權。

下表摘要說明各項文件動作所需的角色。如要進一步瞭解各角色獲得的權限，請參閱「IAM 角色和權限」。

如要使用服務帳戶呼叫 Document Schema API，請參閱projects.locations.documentSchemas。

Document API 方法	必要的角色
`CreateDocument`	`roles/contentwarehouse.documentCreator`
`UpdateDocument`	`roles/contentwarehouse.documentEditor`
`DeleteDocument` `SetACL`	`roles/contentwarehouse.documentAdmin`
`GetDocument` `FetchACL` `SearchDocuments`	`roles/contentwarehouse.documentViewer`

CreateDocument

如果尚未授予使用者或群組「建立者」存取權，請執行下列操作：

[選用] 從客戶的 ID 服務擷取使用者管理員的成員群組。如果客戶使用 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 查看文件的存取控制清單。步驟如下：

選用：從身分識別服務擷取使用者 A 的成員群組。如果您使用 Cloud Identity，可以略過這個步驟。
使用服務帳戶，在要求中繼資料中加入使用者 A (和成員群組)，然後呼叫 GetDocument 或 FetchAcl。

如果 B 不是 groupX、groupY 或 groupZ 的成員，系統會拒絕 B 的來電。

UpdateDocument、DeleteDocument 和 SetAcl

建立文件後，只有使用者 A 或群組 Y/Z 的成員可以呼叫 UpdateDocument 更新文件；只有使用者 A 或群組 Z 的成員可以呼叫 DeleteDocument 刪除文件，或呼叫 SetAcl 與其他使用者或群組共用文件。步驟如下：

選用：從身分識別服務擷取使用者 A 的成員群組。如果您使用 Cloud Identity，可以略過這個步驟。
使用服務帳戶，在要求中加入使用者 A [和成員群組] 的中繼資料，然後呼叫 UpdateDocument、DeleteDocument 或 SetAcl。

由於群組 X 的成員只有文件的 documentViewer 存取權，因此系統會拒絕他們的通話。

SearchDocuments

系統會根據授予使用者的角色傳回文件。舉例來說，如果搜尋查詢為空白，且使用者在專案層級擁有 documentViewer 存取權，系統就會傳回專案中的所有文件。否則，系統只會傳回指定使用者擁有 contentwarehouse.documents.get 權限的文件。

如要呼叫 SearchDocument API，顧客必須執行下列步驟。

選用：從身分識別服務擷取使用者 A 的成員群組。如果您使用 Cloud Identity，可以略過這個步驟。
使用服務帳戶，在要求中繼資料中加入使用者 A (和成員群組)，然後呼叫 SearchDocument。

文件連結 API

Document Link API 方法	必要的角色
`CreateDocumentLink`	來源： `roles/contentwarehouse.documentEditor` 目標： `roles/contentwarehouse.documentViewer`
`ListLinkedTargets` `ListLinkedSources`	`roles/contentwarehouse.documentViewer`
`DeleteDocumentLink`	來源： `roles/contentwarehouse.documentEditor`

CreateDocumentLink

如果使用者對文件 1 具有 contentwarehouse.documents.update 權限，對文件 2 具有 contentwarehouse.documents.get 權限，即可連結文件 1 和文件 2。

ListLinkedTargets 和 ListLinkedSources

只有具備 contentwarehouse.documents.get 權限，使用者才能列出目標或來源文件。

DeleteDocumentLink

如果使用者對來源文件擁有 contentwarehouse.documents.update 權限，就能刪除連結。