액세스 제어 관리

이 페이지에서는 프로젝트 및 문서의 액세스 제어를 관리하는 방법을 간략히 설명합니다.

데이터 액세스 제어 개요

데이터 액세스 제어는 Document AI Warehouse의 주요 기능입니다. Document AI Warehouse에서 어떤 리소스에 액세스할 수 있는 사용자와 해당 사용자의 액세스 수준을 제어합니다.

Document AI Warehouse API는 Google Cloud를 기반으로 빌드됩니다. HTTPS는 인터넷을 통한 안전한 데이터 전송을 보장하는 데 사용됩니다. 인증 및 승인은 Google ID를 기반으로 서비스와 사용자 데이터를 보호하기 위해 Document AI Warehouse API에서 적용됩니다.

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는 세 가지 액세스 제어 모드를 제공합니다.

범용 액세스: 문서 수준 액세스 제어 없음
자체 ID 서비스의 사용자가 포함된 문서 수준 액세스 제어
Cloud ID를 사용한 문서 수준 액세스 제어

사용자는 프로비저닝 프로세스 중에 액세스 모드 중 하나를 선택해야 합니다. 다음 섹션에서는 세 가지 액세스 제어 모드의 차이점을 설명하고 각 모드를 사용 설정하는 방법을 보여줍니다.

어디서나 액세스 가능

범용 액세스 제어를 사용하면 Identity and Access Management (IAM)만으로 권한을 관리할 수 있습니다. IAM은 인증된 ID가 있는 프로젝트의 모든 문서에 동일한 권한을 적용합니다.

이 모드에서는 빠른 시작 가이드의 프로비저닝 절차를 완료하면 서비스 계정을 사용하여 Document AI Warehouse 서비스에서 선택한 Google Cloud프로젝트의 모든 문서에 액세스할 수 있습니다. 이때 서비스 계정과 연결된 권한이 사용됩니다.

이 문서의 나머지 부분에서는 문서 수준 액세스 제어를 설명합니다. 범용 액세스를 사용하는 경우 문서의 나머지 부분을 건너뛰어도 됩니다.

문서 수준 액세스 제어

Document AI Warehouse 사용자는 다음 중 한 가지 작업을 할 수 있습니다.

자체 ID 서비스 사용
- 최종 사용자와 최종 사용자 멤버십 그룹은 요청 메타데이터에 모두 필요합니다. 회사에서 사용자를 인증하고 사용자가 속한 그룹을 식별하는 자체 방식이 있는 경우 이 옵션을 사용하세요.
Cloud ID 사용
- Document AI Warehouse는 고객의 Cloud ID에서 멤버십 그룹을 수집하므로 요청 메타데이터에는 최종 사용자만 필요합니다. 이 방법과 맞춤 ID 서비스를 사용하는 방법의 차이점은 사내 시스템이 아닌 Cloud ID를 사용하여 사용자의 그룹 멤버십을 관리한다는 것입니다.

문서 수준 액세스 모드를 사용할 때는 몇 가지 제한사항이 있습니다.

ACL의 구성원과 역할만 지원됩니다. IAM 조건은 무시됩니다.
ACL에서는 맞춤 역할이 지원되지 않습니다.
Document AI Warehouse는 최종 사용자 인증 정보를 확인하지 않습니다. Document AI Warehouse는 호출이 고객으로부터 온 것인지 확인하기 위해 서비스 계정 사용자 인증 정보만 확인합니다. 최종 사용자 인증 정보는 고객 측에서 확인해야 합니다.
액세스 제어를 적용하려면 고객이 요청 메타데이터에 최종 사용자 (Cloud ID 옵션을 사용하지 않는 경우 최종 사용자가 속한 모든 그룹)를 제공해야 합니다.
최종 사용자의 멤버십 그룹 수는 100개 미만이어야 합니다.

고객의 자체 ID 서비스가 포함된 문서 수준 액세스 제어

다음과 같은 경우 이 모드를 선택할 수 있습니다.

각 문서에 액세스할 수 있는 권한을 최종 사용자 (그룹)에게 다르게 부여합니다.
자체 ID 서비스를 사용합니다.

이 모드를 사용하면 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을 설정할 수도 있습니다.

위 단계를 완료하면 이제 서비스 계정을 사용하여 요청 본문의 RequestMetadata 섹션에 최종 사용자 및 그룹 멤버십 정보와 함께 Document AI Warehouse에 API 호출을 할 수 있습니다.

이 모드에서는 프록시를 배포하여 최종 사용자를 인증하고 승인해야 합니다. 프록시는 관리자 역할이 부여된 서비스 계정을 사용하여 서비스에 액세스합니다. 서비스 계정 키는 프록시에서만 사용되도록 보호해야 합니다.

기본 제공 솔루션인 Document AI Warehouse 콘솔은 서비스 계정 키를 저장하고, Google ID를 통해 최종 사용자를 인증하고, Document AI Warehouse로 요청을 전달할 수 있는 프록시입니다.

Cloud ID를 사용한 문서 수준 액세스 제어

자체 ID 서비스를 사용하는 대신 Cloud ID를 사용하여 프로세스를 간소화할 수도 있습니다.

사용자와 그룹을 중앙에서 관리하기 위해 Google Cloud 고객은 처음부터 Cloud ID를 설정하거나 Google과 다른 ID 공급업체(예: Active Directory, Azure Active Directory) 간의 ID를 제휴할 수 있습니다.

API 호출에 제공된 RequestMetadata의 UserInfo 섹션은 최종 사용자가 요청된 문서 리소스에 대해 해당 작업을 실행할 수 있는지 확인하는 데 사용됩니다. Cloud ID를 사용하면 RequestMetadata에 최종 사용자 ID만 필요하며 Document AI Warehouse는 Cloud ID 서비스에서 멤버십 그룹 정보를 수집합니다. 최종 사용자 또는 멤버십 그룹 중 하나가 문서에 액세스할 수 있는 경우 최종 사용자가 문서에 액세스할 수 있습니다.

JSON 형식의 RequestMetadata 샘플:

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

빠른 시작 가이드를 따르는 것 외에도 이 액세스 제어 모드에서는 Document AI Warehouse에 요청을 보내기 전에 몇 가지 추가 단계가 필요합니다.

최종 사용자 및 그룹을 위해 Cloud ID와 통합
액세스 제어 구성 섹션의 안내에 따라 기본 프로젝트 정책을 설정합니다. 생성 후 특정 문서에 대해 문서 수준 ACL을 설정할 수도 있습니다.

위 단계를 완료하면 이제 서비스 계정을 사용하여 요청 본문의 RequestMetadata 섹션에 최종 사용자 정보가 포함된 Document AI Warehouse에 API 호출을 할 수 있습니다.

액세스 제어 구성

시작하기 전에

시작하기 전에 빠른 시작 페이지를 완료했는지 확인하세요.

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

최종 사용자 또는 그룹에 생성자 액세스 권한이 부여되지 않은 경우 부여합니다.

[선택사항] 고객의 ID 서비스에서 최종 사용자 관리자의 멤버십 그룹을 가져옵니다. Cloud ID를 사용하는 고객은 이 단계를 건너뛸 수 있습니다.
요청 메타데이터에서 최종 사용자 관리자 [및 멤버십 그룹] 이 있는 서비스 계정을 사용하여 SetAcl를 호출하여 프로젝트 수준에서 최종 사용자 A (또는 사용자 A가 속한 그룹)에게 roles/contentwarehouse.documentCreator 역할을 부여합니다. 최종 사용자 관리자에게 프로젝트 수준의 documentAdmin 액세스 권한이 있습니다.

문서 만들기:

선택사항: ID 서비스에서 최종 사용자 A의 멤버십 그룹을 가져옵니다. Cloud ID를 사용하는 경우 이 단계를 건너뛸 수 있습니다.
요청 메타데이터에서 최종 사용자 A[및 멤버십 그룹] 와 함께 CreateDocument를 호출하여 서비스 계정을 사용하여 문서를 만듭니다. 문서가 생성되면 최종 사용자 A는 기본적으로 문서를 보고 수정할 수 있습니다. 고객은 생성 중에 사용자 또는 그룹에 액세스 권한을 부여하는 기본 정책을 지정할 수도 있습니다. 예를 들어 groupX에 documentViewer 액세스 권한을 부여하고 groupY에 documentEditor 액세스 권한을 부여하고 groupZ에 documentAdmin 액세스 권한을 부여합니다.

GetDocument 및 FetchAcl

문서가 생성되면 최종 사용자 A 또는 groupX, groupY, groupZ의 구성원이 GetDocument를 호출하여 문서를 보거나 FetchAcl를 호출하여 문서의 ACL을 볼 수 있습니다. 단계별로 알려드리겠습니다.

선택사항: ID 서비스에서 최종 사용자 A의 멤버십 그룹을 가져옵니다. Cloud ID를 사용하는 경우 이 단계를 건너뛸 수 있습니다.
요청 메타데이터에 최종 사용자 A (및 멤버십 그룹)가 있는 서비스 계정을 사용하여 GetDocument 또는 FetchAcl를 호출합니다.

B가 groupX, groupY 또는 groupZ의 구성원이 아닌 경우 최종 사용자 B의 통화가 거부됩니다.

UpdateDocument, DeleteDocument, SetAcl

문서가 생성된 후에는 최종 사용자 A 또는 groupY 또는 groupZ의 구성원만 UpdateDocument를 호출하여 문서를 업데이트할 수 있으며, 최종 사용자 A 또는 groupZ의 구성원만 DeleteDocument를 호출하여 문서를 삭제하거나 SetAcl를 호출하여 다른 최종 사용자 또는 그룹과 문서를 공유할 수 있습니다. 단계별로 알려드리겠습니다.

선택사항: ID 서비스에서 최종 사용자 A의 멤버십 그룹을 가져옵니다. Cloud ID를 사용하는 경우 이 단계를 건너뛸 수 있습니다.
요청 메타데이터에서 최종 사용자 A[및 멤버십 그룹] 가 있는 서비스 계정을 사용하여 UpdateDocument, DeleteDocument 또는 SetAcl를 호출합니다.

groupX의 구성원은 문서에 대한 documentViewer 액세스 권한만 있으므로 통화가 거부됩니다.

SearchDocuments

반환되는 문서는 최종 사용자에게 부여된 역할에 따라 달라집니다. 예를 들어 빈 검색어의 경우 최종 사용자에게 프로젝트 수준에서 documentViewer 액세스 권한이 있으면 프로젝트의 모든 문서가 반환됩니다. 그렇지 않으면 지정된 최종 사용자에 대해 contentwarehouse.documents.get 권한이 있는 문서만 반환됩니다.

SearchDocument API를 호출하려면 고객이 다음 단계를 수행해야 합니다.

선택사항: ID 서비스에서 최종 사용자 A의 멤버십 그룹을 가져옵니다. Cloud ID를 사용하는 경우 이 단계를 건너뛸 수 있습니다.
요청 메타데이터에서 최종 사용자 A(및 멤버십 그룹)가 있는 서비스 계정을 사용하여 SearchDocument를 호출합니다.

문서 링크 API

문서 링크 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 권한이 있는 경우 링크를 삭제할 수 있습니다.