Memetakan ACL

Untuk memastikan bahwa hanya pengguna yang memiliki akses ke item yang dapat melihat item tersebut dalam hasil penelusuran, Anda harus mengindeks item dengan daftar kontrol akses (ACL) dari repositori perusahaan. Anda harus membuat model ACL repositori dan menyertakan ACL tersebut saat mengindeks item dalam repositori. Content Connector SDK menyediakan serangkaian metode ACL yang cukup kuat untuk membuat model ACL di sebagian besar repositori.

Catatan: Content Connector SDK mendukung ACL domain tunggal, tetapi tidak mendukung ACL lintas domain. Anda tidak dapat memberikan akses ke pengguna dan grup yang berada di luar organisasi Anda. Setiap ACL yang merujuk pada pengguna atau grup di luar organisasi Anda tidak akan berlaku.

Membuat ACL

Membuat ACL merupakan proses dua langkah:

1. Buat Principal menggunakan metode statis di class ACL.
2. Gunakan class Acl.Builder untuk membuat ACL menggunakan akun utama.

Bagian selanjutnya dari dokumen ini membahas beberapa konsep yang perlu Anda ketahui untuk membuat model dan membuat ACL, seperti pewarisan dan pemuatan.

Membuat entity utama menggunakan ID eksternal

Google Cloud Search mengharuskan pengguna dan grup untuk menangani alamat email Google. Saat mengindeks item repositori, konektor konten mungkin tidak memiliki alamat email ini. Namun, Content Connector SDK memungkinkan Anda menggunakan setiap ID eksternal (ID yang memberi pengguna atau grup akses ke item repositori), sebagai pengganti alamat email, untuk mengindeks item. Gunakan metode getUserPrincipal() atau metode getGroupPrincpal() untuk membuat akun utama yang berisi ID eksternal. Ada beberapa metode statis lainnya di class ACL yang digunakan untuk membuat objek Principal.

Catatan: Pengguna tidak akan melihat item dalam hasil penelusuran hingga ID eksternalnya disinkronkan dengan akun Google miliknya. Sinkronisasi ID pengguna atau grup eksternal ini ke alamat email Google dapat dilakukan menggunakan konektor identitas. Untuk mengetahui informasi selengkapnya tentang konektor identitas, lihat Membuat konektor identitas.

Peringatan: Setelah memetakan ulang identitas item ke identitas lain, Anda harus melakukan pengindeksan ulang item agar identitas baru dapat diterapkan. Untuk informasi lebih lanjut, lihat Memetakan ulang identitas.

Pewarisan ACL

Pewarisan ACL mengacu pada otorisasi, untuk item dan pengguna tertentu, berdasarkan hasil kombinasi antara ACL item dan ACL rantai pewarisannya. Aturan yang digunakan untuk membuat keputusan otorisasi bergantung pada repositori dan properti item.

Menetapkan pewarisan

Setiap item dapat memiliki entity utama langsung yang diizinkan dan entity utama langsung yang ditolak, yang ditentukan menggunakan metode setReaders() dan setDeniedReaders(). Entity utama langsung yang diizinkan adalah pengguna yang diidentifikasi dalam ACL, yang diberi akses langsung ke item tertentu. Entity utama langsung yang ditolak adalah pengguna yang diidentifikasi dalam ACL sebagai tidak memiliki akses ke item tertentu.

Item juga dapat mewarisi entity utama tidak langsung yang diizinkan dan entity utama tidak langsung yang ditolak menggunakan metode setInheritFrom(). Entity utama tidak langsung yang diizinkan adalah pengguna yang memiliki akses tidak langsung ke item tertentu melalui pewarisan ACL. Entity utama tidak langsung yang ditolak adalah pengguna yang ditolak aksesnya ke item tertentu melalui pewarisan ACL.

Catatan: Jika menetapkan pewarisan menggunakan metode setInheritFrom(), Anda harus menetapkan jenis pewarisan menggunakan metode setInheritanceType(). Untuk mengetahui informasi tentang jenis pewarisan, lihat Menetapkan jenis pewarisan.

Gambar 1 menunjukkan penggunaan metode setInheritFrom() untuk mewarisi entity utama tidak langsung yang diizinkan dan entity utama tidak langsung yang ditolak.

Gambar 1. Metode setInheritFrom().

Kontrol akses ini direpresentasikan pada Gambar 1:

• Pengguna 1 adalah entity utama langsung yang diizinkan dari item A.
• Pengguna 2 adalah entity utama langsung yang diizinkan dari item B.
• Item B mewarisi ACL dari item A.

Berdasarkan kontrol akses tersebut, aturan aksesnya adalah:

• Pengguna 1 tidak perlu ditentukan secara eksplisit sebagai entity utama dari item B untuk menjadi entity utama tidak langsung yang diizinkan dari item B; akses diwarisi karena Pengguna 1 terdaftar sebagai entity utama langsung yang diizinkan dari item A dan item B mewarisi ACL dari item A.
• Pengguna 2 bukan entity utama tidak langsung yang diizinkan untuk item A.

Menetapkan jenis pewarisan

Jika menetapkan pewarisan menggunakan metode setInheritFrom(), Anda harus menetapkan jenis pewarisan menggunakan metode setInheritanceType(). Jenis pewarisan menentukan kombinasi ACL turunan dengan ACL induknya. Acl.InheritanceType mengimplementasikan tiga jenis pewarisan:

• BOTH_PERMIT - Menetapkan jenis pewarisan ke BOTH_PERMIT untuk memberi pengguna akses ke item hanya jika ACL item turunan dan ACL item induk yang diwarisi mengizinkan pengguna untuk mengakses item tersebut.

• CHILD_OVERRIDE - Menetapkan jenis pewarisan ke CHILD_OVERRIDE untuk menerapkan ACL item turunan agar lebih diprioritaskan daripada ACL item induk yang diwarisi saat keduanya bentrok. Jadi, jika ACL item induk menolak akses pengguna sebagai pembaca yang ditolak, pengguna masih memiliki akses jika ia memiliki akses ke item turunan sebagai pembaca. Sebaliknya, meskipun ACL item induk memberikan akses kepada pengguna, pengguna tidak akan memiliki akses jika ia adalah pembaca yang ditolak dari ACL item turunan.

• PARENT_OVERRIDE - Menetapkan jenis pewarisan ke PARENT_OVERRIDE untuk menerapkan ACL item induk agar lebih diprioritaskan daripada ACL item turunan saat keduanya bentrok. Jadi, jika ACL item turunan menolak akses pengguna sebagai pembaca yang ditolak, pengguna masih memiliki akses jika ia memiliki akses ke item induk sebagai pembaca. Sebaliknya, meskipun ACL item turunan memberikan akses kepada pengguna, pengguna tidak memiliki akses jika ia adalah pembaca yang ditolak dari ACL item induk.

Saat mengevaluasi rantai pewarisan ACL, urutan evaluasi dapat mengubah hasil keputusan otorisasi. Cloud Search menyediakan urutan evaluasi menyeluruh untuk rantai pewarisan ACL. Secara khusus, keputusan ACL untuk suatu rantai dimulai dengan mengevaluasi turunan dengan induknya, dan dapat berlanjut hingga induk root.

Misalnya, jika turunan memiliki jenis pewarisan CHILD_OVERRIDE dan pengguna memiliki akses ke turunan, Drive tidak perlu mengevaluasi induk. Namun, jika turunan memiliki PARENT_OVERRIDE atau BOTH_PERMIT, Drive akan terus mengevaluasi pewarisan lebih lanjut di rantai.

Pemuatan dan penghapusan item

Saat mengindeks item, Anda dapat memberi label pada item sebagai penampung menggunakan metode setContainer() dari class IndexingItemBuilder. Hubungan container/containee menetapkan hierarki fisik item dan memastikan item dihapus dengan benar. Saat container dihapus, item yang ada pada container tersebut juga akan dihapus.

Hubungan pemuatan sepenuhnya tidak bergantung pada aturan pewarisan ACL. Sebagai contoh, file pada sistem file dapat disimpan dalam folder untuk tujuan penghapusan, tetapi mewarisi ACL dari folder yang berbeda. Menghapus folder tidak akan menghapus item yang mewarisi ACL-nya, kecuali item tersebut juga berada dalam hierarki pemuatan folder.

Kontrol akses ini direpresentasikan pada Gambar 2:

• Pengguna 1 adalah entity utama langsung yang diizinkan dari item A.
• Pengguna 2 adalah entity utama langsung yang diizinkan dari item B.
• Pengguna 3 adalah entity utama langsung yang diizinkan dari item C.
• Item C mewarisi ACL dari item A.
• Item B menyebut item A sebagai container-nya.
• Item C menyebut item B sebagai container-nya.

Berdasarkan kontrol akses tersebut, aturan aksesnya adalah:

• Akses tidak langsung berasal dari metode setInheritFrom(). Oleh karena itu, pengguna 1 dapat mengakses item C karena item C mewarisi ACL dari item A.
• Akses tidak langsung tidak berasal dari item C yang ada dalam item B. Oleh karena itu, pengguna 2 tidak dapat mengakses item C.

Gambar 2. Metode setInheritFrom() yang digunakan.

Pemisahan pewarisan ACL dari hierarki pemuatan memungkinkan Anda membuat model berbagai struktur yang ada.

Saat item berhasil dihapus:

• Semua item yang berisi item yang dihapus menjadi tidak dapat ditelusuri dan dijadwalkan untuk dihapus dari sumber data Google.
• Setiap item yang telah menentukan item yang dihapus menggunakan metode setInheritFrom() menjadi tidak dapat ditelusuri.

Jika resource memiliki item yang dihapus menggunakan metode setInheritFrom(), tetapi tidak memiliki penampung yang ditetapkan menggunakan setContainer(), atau hierarki pemuatannya tidak berisi item yang dihapus, item tersebut beserta datanya tetap ada dalam sumber data Google. Anda harus menghapus item tersebut.

Gambar 3 menunjukkan contoh cara kerja penghapusan untuk hierarki item.

Gambar 3. Menghapus item dan pewarisan ACL.

Kontrol akses ini direpresentasikan pada Gambar 3:

• Pengguna 1 adalah entity utama langsung yang diizinkan dari item A.
• Pengguna 2 adalah entity utama langsung yang diizinkan dari item D.
• Item D dan item E mewarisi ACL dari item A.
• Item D menyebut item A sebagai container-nya.
• Item A dan E merupakan item tingkat root karena tidak memiliki item container.

Penghapusan menurun melalui referensi container. Saat item A dihapus:

• Semua turunan referensi setInheritFrom() kehilangan akses untuk semua pengguna.
• Tidak ada pengguna yang dapat mengakses item A.
• Item D dihapus secara implisit. Tidak ada pengguna yang dapat mengakses item D.
• Item E tidak dihapus karena penghapusan hanya menurun melalui referensi container.
• Item E menjadi tidak dapat dijangkau dan tidak ada pengguna yang dapat menelusuri item E.