Mengelola kontrol akses

Perhatian: Document AI Warehouse tidak digunakan lagi dan tidak akan tersedia lagi di Google Cloud setelah 16 Januari 2025. Untuk mengamankan data Anda, migrasikan dokumen yang saat ini disimpan di Document AI Warehouse ke alternatif seperti Cloud Storage. Pastikan migrasi data Anda selesai sebelum tanggal penghentian untuk mencegah kehilangan data. Lihat Penghentian penggunaan untuk mengetahui detailnya.

Halaman ini memberikan ringkasan tentang cara mengelola kontrol akses untuk project dan dokumen.

Ringkasan Kontrol Akses Data

Kontrol Akses Data adalah fitur utama Document AI Warehouse. IAM mengontrol siapa yang memiliki akses ke resource mana di Document AI Warehouse, dan tingkat akses yang mereka miliki.

API Document AI Warehouse dibangun di atas Google Cloud. HTTPS digunakan untuk memastikan transmisi data yang aman melalui internet. Autentikasi dan otorisasi diterapkan pada Document AI Warehouse API untuk melindungi layanan dan data pengguna berdasarkan identitas Google.

Document AI Warehouse API menggunakan OAuth2 untuk autentikasi dengan akun pengguna. Semua metode API memerlukan cakupan OAuth https://www.googleapis.com/auth/cloud-platform.

Document AI Warehouse menerapkan kontrol akses untuk data pelanggan, berdasarkan Cloud IAM. Document AI Warehouse menentukan serangkaian peran dan izin terkait agar Anda dapat membatasi akses pengguna yang berbeda ke data yang disimpan dalam layanan kami. Untuk mengetahui informasi selengkapnya, lihat bagian Peran dan izin IAM.

Menggunakan akun layanan untuk menerapkan kontrol akses dasar

Anda memerlukan akun layanan yang diberi izin yang diperlukan untuk mengakses Document AI Warehouse API. Jika Anda melalui langkah "Sediakan melalui konsol" di panduan Mulai Cepat, akun layanan akan disediakan secara otomatis dengan peran Admin Document AI Warehouse. Google Cloud

Catatan: Jika Anda memilih model akses universal seperti yang dijelaskan di bagian berikut, akun layanan ini adalah semua yang Anda butuhkan untuk mengakses layanan Document AI Warehouse. Jika tidak, Anda juga harus meneruskan kontrol akses tingkat dokumen berdasarkan identitas yang diklaim dalam permintaan.

Mode kontrol akses

Document AI Warehouse menyediakan tiga mode kontrol akses:

• Akses universal: Tidak ada kontrol akses tingkat dokumen
• Kontrol akses tingkat dokumen dengan layanan identitas Anda sendiri
• Kontrol akses tingkat dokumen dengan Cloud Identity

Pengguna harus memilih salah satu mode akses selama proses penyediaan. Bagian berikut menguraikan perbedaan antara tiga mode kontrol akses, dan menunjukkan cara mengaktifkan setiap mode.

Akses universal

Kontrol akses universal memungkinkan Anda menggunakan Identity and Access Management (IAM) saja untuk mengelola izin. IAM menerapkan izin yang sama ke semua dokumen dalam project dengan identitas yang diautentikasi.

Dalam mode ini, setelah Anda menyelesaikan prosedur penyediaan di panduan quickstart, Anda dan semua pengguna Anda dapat mengakses semua dokumen di project Google Cloud yang dipilih dalam layanan Document AI Warehouse menggunakan akun layanan, dengan izin yang terkait dengan akun layanan.

Bagian selanjutnya dari dokumen ini membahas kontrol akses tingkat dokumen. Jika Anda menggunakan akses universal, silakan lewati bagian dokumen lainnya.

Kontrol akses tingkat dokumen

Untuk pengguna Document AI Warehouse, Anda dapat:

• Gunakan layanan identitas Anda sendiri
  • Grup keanggotaan pengguna akhir dan pengguna akhir diperlukan dalam metadata permintaan. Jika perusahaan Anda memiliki cara sendiri untuk mengautentikasi pengguna dan mengidentifikasi grup tempat pengguna berada, gunakan opsi ini.
• Menggunakan Cloud Identity
  • Hanya pengguna akhir yang diperlukan dalam metadata permintaan karena Document AI Warehouse mengumpulkan grup keanggotaan dari Cloud Identity untuk pelanggan. Perbedaan antara cara ini dan penggunaan layanan identitas kustom adalah Anda mengelola keanggotaan grup pengguna menggunakan Cloud Identity, bukan sistem internal.

Ada beberapa batasan dalam menggunakan mode akses tingkat dokumen:

• Hanya anggota dan peran dalam ACL yang didukung. IAM conditions diabaikan.
• Peran kustom tidak didukung di ACL.
• Document AI Warehouse tidak memverifikasi kredensial pengguna akhir. Document AI Warehouse hanya memverifikasi kredensial akun layanan untuk memastikan panggilan berasal dari pelanggan. Kredensial pengguna akhir harus diverifikasi di sisi pelanggan.
• Pelanggan harus memberikan pengguna akhir (dan semua grup yang beranggotakan pengguna akhir jika tidak menggunakan opsi Cloud Identity) dalam metadata permintaan untuk menerapkan kontrol akses.
• Jumlah grup keanggotaan untuk pengguna akhir harus kurang dari 100.

Kontrol akses tingkat dokumen dengan layanan identitas milik pelanggan

Anda dapat memilih mode ini jika ingin melakukan hal berikut:

• Memberi pengguna akhir (grup) izin yang berbeda untuk mengakses setiap dokumen.
• Gunakan layanan identitas Anda sendiri.

Mode ini memungkinkan Anda menggunakan IAM dan daftar kontrol akses (ACL) secara bersamaan untuk mengelola izin. Setiap dokumen di Document AI Warehouse dapat dikonfigurasi dengan ACL tingkat dokumen tertentu. Autentikasi dan otorisasi terjadi sebagai berikut:

• Kredensial akun layanan diautentikasi dan diotorisasi untuk mengakses layanan.
• Dalam metadata permintaan, sertakan pengguna akhir dan grup keanggotaan pengguna akhir. Pengguna akhir atau setidaknya salah satu grup tempat pengguna akhir berada harus memiliki izin untuk mengakses dokumen.

Document AI Warehouse memberikan akses ke dokumen yang diminta hanya jika kedua kondisi dalam daftar sebelumnya terpenuhi.

UserInfo (termasuk ID pengguna akhir dan ID grup keanggotaan pengguna) dari RequestMetadata yang diberikan dalam panggilan API digunakan untuk memvalidasi apakah pengguna akhir diizinkan melakukan tindakan yang sesuai terhadap resource dokumen yang diminta. Misalnya, UserInfo yang diberikan di GetDocument API digunakan untuk memvalidasi apakah pengguna akhir diizinkan melihat dokumen. Jika pengguna akhir atau salah satu grup keanggotaan diizinkan untuk melihat dokumen, pengguna akhir tersebut diizinkan untuk melihat dokumen.

Contoh RequestMetadata dalam format 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,
        ]
    }
}

Selain mengikuti panduan Mulai Cepat, mode kontrol akses ini memerlukan beberapa langkah tambahan sebelum Anda mulai mengirimkan API ke Document AI Warehouse:

1. Mengambil informasi keanggotaan grup untuk pengguna akhir tertentu dari layanan direktori Anda (misalnya, Azure Active Directory atau Okta).
2. Ikuti petunjuk di bagian Mengonfigurasi kontrol akses untuk menetapkan kebijakan project default. Anda juga dapat menetapkan ACL tingkat dokumen untuk dokumen tertentu setelah dibuat.

Setelah menyelesaikan langkah-langkah sebelumnya, Anda kini siap menggunakan akun layanan untuk melakukan panggilan API ke Document AI Warehouse dengan info keanggotaan grup dan pengguna akhir di bagian RequestMetadata isi permintaan.

Dalam mode ini, Anda harus men-deploy proxy untuk mengautentikasi dan mengotorisasi pengguna akhir. Proxy menggunakan akun layanan yang diberi peran admin untuk mengakses layanan. Kunci akun layanan harus dilindungi agar hanya digunakan oleh proxy.

Sebagai solusi siap pakai, konsol Document AI Warehouse adalah proxy yang dapat menyimpan kunci akun layanan, mengautentikasi pengguna akhir melalui identitas Google, dan meneruskan permintaan ke Document AI Warehouse.

Kontrol akses tingkat dokumen dengan Cloud Identity

Sebagai alternatif untuk menggunakan layanan identitas Anda sendiri, Anda juga dapat memilih untuk menggunakan Cloud Identity guna menyederhanakan proses.

Untuk mengelola pengguna dan grup secara terpusat, Google Cloud pelanggan dapat menyiapkan Cloud Identity dari awal atau menggabungkan identitas antara Google dan penyedia identitas lainnya, seperti Active Directory dan Azure Active Directory.

Bagian UserInfo dari RequestMetadata yang diberikan dalam panggilan API digunakan untuk memvalidasi apakah pengguna akhir diizinkan untuk melakukan tindakan yang sesuai terhadap resource dokumen yang diminta. Dengan menggunakan Cloud Identity, hanya ID pengguna akhir yang diperlukan di RequestMetadata, dan Document AI Warehouse mengumpulkan informasi grup keanggotaan dari layanan Cloud Identity. Jika pengguna akhir atau salah satu grup keanggotaan diizinkan mengakses dokumen, pengguna akhir diizinkan mengakses dokumen tersebut.

Contoh RequestMetadata dalam format JSON:

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

Selain mengikuti panduan Mulai Cepat, mode kontrol akses ini memerlukan beberapa langkah tambahan sebelum Anda mulai mengirim permintaan ke Document AI Warehouse:

1. Terintegrasi dengan Cloud Identity untuk pengguna akhir dan grup.
2. Ikuti petunjuk di bagian Mengonfigurasi kontrol akses untuk menetapkan kebijakan project default. Anda juga dapat menetapkan ACL tingkat dokumen untuk dokumen tertentu setelah dibuat.

Setelah menyelesaikan langkah-langkah sebelumnya, Anda kini siap menggunakan akun layanan untuk melakukan panggilan API ke Document AI Warehouse dengan informasi pengguna akhir di bagian RequestMetadata isi permintaan.

Mengonfigurasi kontrol akses

Sebelum memulai

Sebelum memulai, pastikan Anda telah menyelesaikan halaman Mulai Cepat.

Catatan: Halaman ini hanya relevan jika Anda menggunakan kontrol akses tingkat dokumen untuk project Anda. Jika memilih kontrol akses universal untuk project, Anda dapat melewati bagian selanjutnya dari dokumen ini.

SetAcl dan FetchAcl

Saat project baru dibuat, tidak ada ACL project yang ditetapkan. Pemilik project dapat memanggil Document AI Warehouse API SetAcl untuk menetapkan kebijakan project default menggunakan peran yang telah ditentukan sebelumnya untuk project dengan menyetel kolom projectOwner ke benar menggunakan akun layanan. Anggota dalam kebijakan project memiliki akses ke semua dokumen dalam project, bergantung pada peran yang diberikan. Anda dapat memberikan akses kepada pengguna atau grup admin dalam kebijakan project default.

Catatan: Memanggil SetAcl akan menggantikan ACL yang ada untuk project atau dokumen. Agar konfigurasi ACL yang disimpan sebelumnya tidak diganti, Anda dapat memanggil FetchAcl untuk mendapatkan ACL yang ada untuk project atau dokumen terlebih dahulu, dan menyertakannya sebagai bagian dari permintaan SetAcl Anda.

Berikut adalah tabel yang merangkum peran yang diperlukan untuk setiap tindakan dokumen. Untuk mengetahui informasi selengkapnya tentang izin yang diberikan untuk setiap peran, lihat Peran dan izin IAM.

Untuk melakukan panggilan ke Document Schema API menggunakan akun layanan, lihat projects.locations.documentSchemas.

Metode API Dokumen	Peran yang diperlukan
CreateDocument	roles/contentwarehouse.documentCreator
UpdateDocument	roles/contentwarehouse.documentEditor
DeleteDocument SetACL	roles/contentwarehouse.documentAdmin
GetDocument FetchACL SearchDocuments	roles/contentwarehouse.documentViewer

CreateDocument

Berikan akses Pembuat kepada pengguna akhir atau grup jika belum diberikan:

• [Opsional] Mengambil grup keanggotaan untuk Admin pengguna akhir dari layanan identitas pelanggan. Langkah ini dapat dilewati untuk pelanggan yang menggunakan Cloud Identity.
• Beri pengguna akhir A (atau grup yang beranggotakan pengguna A) peran roles/contentwarehouse.documentCreator di tingkat project dengan melakukan panggilan ke SetAcl menggunakan akun layanan dengan Admin pengguna akhir [dan grup keanggotaan] dalam metadata permintaan. Admin pengguna akhir memiliki akses documentAdmin di tingkat project.

Membuat dokumen:

• Opsional: Ambil grup keanggotaan untuk pengguna akhir A dari layanan identitas Anda. Langkah ini dapat dilewati jika Anda menggunakan Cloud Identity.
• Lakukan panggilan ke CreateDocument dengan pengguna akhir A [dan grup keanggotaan] dalam metadata permintaan untuk membuat dokumen menggunakan akun layanan. Setelah dokumen dibuat, pengguna akhir A dapat melihat dan mengedit dokumen secara default. Pelanggan juga dapat menentukan kebijakan default untuk memberikan akses kepada pengguna atau grup selama pembuatan. Misalnya, memberikan akses documentViewer ke grupX, akses documentEditor ke grupY, dan akses documentAdmin ke grupZ.

Catatan: Peran default pembuat dokumen yang diberikan dapat dikonfigurasi dalam konfigurasi project. Dapat berupa documentAdmin, documentEditor, atau documentViewer. Jika tidak disetel, pembuat dokumen akan diberi peran documentAdmin secara default.

GetDocument dan FetchAcl

Setelah dokumen dibuat, pengguna akhir A atau anggota groupX, groupY, atau groupZ dapat memanggil GetDocument untuk melihat dokumen, atau memanggil FetchAcl untuk melihat ACL dokumen. Berikut langkah-langkahnya:

1. Opsional: Ambil grup keanggotaan untuk pengguna akhir A dari layanan identitas Anda. Langkah ini dapat dilewati jika Anda menggunakan Cloud Identity.
2. Lakukan panggilan ke GetDocument atau FetchAcl menggunakan akun layanan dengan pengguna akhir A (dan grup keanggotaan) dalam metadata permintaan.

Panggilan dari pengguna akhir B ditolak jika B bukan anggota groupX, groupY, atau groupZ.

UpdateDocument, DeleteDocument, dan SetAcl

Setelah dokumen dibuat, hanya pengguna akhir A atau anggota groupY atau groupZ yang diizinkan untuk memanggil UpdateDocument untuk memperbarui dokumen; hanya pengguna akhir A atau anggota groupZ yang diizinkan untuk memanggil DeleteDocument untuk menghapus dokumen atau SetAcl untuk membagikan dokumen kepada pengguna akhir atau grup lain. Berikut langkah-langkahnya:

1. Opsional: Ambil grup keanggotaan untuk pengguna akhir A dari layanan identitas Anda. Langkah ini dapat dilewati jika Anda menggunakan Cloud Identity.
2. Lakukan panggilan ke UpdateDocument, DeleteDocument, atau SetAcl menggunakan akun layanan dengan pengguna akhir A [dan grup keanggotaan] dalam metadata permintaan.

Panggilan dari anggota groupX akan ditolak karena mereka hanya memiliki akses documentViewer ke dokumen.

SearchDocuments

Dokumen yang ditampilkan bergantung pada peran yang diberikan kepada pengguna akhir. Misalnya, untuk kueri penelusuran kosong, semua dokumen dalam project akan ditampilkan jika pengguna akhir memiliki akses documentViewer di tingkat project. Jika tidak, hanya dokumen dengan izin contentwarehouse.documents.get untuk pengguna akhir tertentu yang ditampilkan.

Untuk melakukan panggilan ke SearchDocument API, pelanggan harus melakukan langkah-langkah berikut.

1. Opsional: Ambil grup keanggotaan untuk pengguna akhir A dari layanan identitas Anda. Langkah ini dapat dilewati jika Anda menggunakan Cloud Identity.
2. Lakukan panggilan ke SearchDocument menggunakan akun layanan dengan pengguna akhir A (dan grup keanggotaan) dalam metadata permintaan.

API Link Dokumen

Metode Document Link API	Peran yang diperlukan
CreateDocumentLink	Sumber: roles/contentwarehouse.documentEditor Target: roles/contentwarehouse.documentViewer
ListLinkedTargets ListLinkedSources	roles/contentwarehouse.documentViewer
DeleteDocumentLink	Sumber: roles/contentwarehouse.documentEditor

CreateDocumentLink

Pengguna akhir dapat menautkan dokumen doc1 dan dokumen doc2 jika pengguna akhir memiliki izin contentwarehouse.documents.update untuk doc1 dan izin contentwarehouse.documents.get untuk doc2.

ListLinkedTargets dan ListLinkedSources

Pengguna akhir hanya dapat mencantumkan dokumen target atau sumber dengan izin contentwarehouse.documents.get.

DeleteDocumentLink

Pengguna akhir dapat menghapus tautan jika mereka memiliki izin contentwarehouse.documents.update di dokumen sumber.