Secara default, izin Identity and Access Management sesi berada di level project. Dokumen ini menjelaskan cara menggunakan IAM Conditions untuk mengontrol akses yang lebih terperinci ke resource Agent Platform Sessions.
Ringkasan
Dengan IAM Conditions, Anda dapat memberikan akses ke resource sesi dan acara sesi
hanya jika kondisi tertentu terpenuhi. Anda dapat mengontrol akses ke sesi berdasarkan string userId dalam resource Sesi menggunakan atribut API aiplatform.googleapis.com/sessionUserId dengan ekspresi yang ditulis dalam Common Expression Language. ID Pengguna adalah string arbitrer yang diberikan saat
membuat sesi, seperti userId = "userA".
Kebijakan Identity and Access Management bersyarat ini dibuat di level project dan berlaku untuk semua sesi dan peristiwa sesi dalam sebuah project. Anda dapat menerapkan kondisi IAM ke semua jenis akun utama, termasuk pengguna project dan akun layanan Anda.
IAM Conditions berguna untuk memberikan izin Identity and Access Management (IAM) ke banyak resource sesi terkait secara bersamaan, termasuk resource yang belum ada. Anda dapat membatasi akses ke sesi dan acara Anda sehingga pengguna hanya dapat mengakses informasi mereka sendiri, atau sehingga developer hanya dapat melihat resource Sesi tertentu tanpa pemberian izin khusus.
Sebelum memulai
Untuk menyiapkan kebijakan Identity and Access Management bersyarat untuk sesi dan peristiwa sesi, lakukan hal berikut:
- Tinjau IAM Conditions: Pelajari ringkasan IAM Conditions.
- Tentukan peran yang diperlukan: Identifikasi peran IAM Sesi khusus yang sesuai untuk kasus penggunaan Anda guna memastikan prinsip hak istimewa terendah.
-
Identifikasi akun utama yang terpengaruh: Identifikasi siapa saja dalam organisasi Anda yang harus menerima izin tertentu. Misalnya, pertimbangkan hal berikut:
- Haruskah pengguna dapat melihat sesi pengguna lain?
- Apakah developer dapat melihat semua sesi?
- Apakah administrator project dapat melihat semua sesi?
- Apakah identitas agen tertentu dapat mengakses sesi tertentu?
-
Memberikan peran IAM: Pastikan Anda memiliki peran yang diperlukan
yang berisi izin yang diperlukan untuk melakukan tugas dalam dokumen
ini.
Untuk mendapatkan izin yang Anda perlukan untuk menerapkan IAM Condition ke resource Agent Platform Sessions , minta administrator untuk memberi Anda peran IAM berikut:
- Untuk project: Project IAM Admin (`roles/resourcemanager.projectIamAdmin`)
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk menerapkan IAM Conditions ke resource Agent Platform Sessions . Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:
Izin yang diperlukan
Izin berikut diperlukan untuk menerapkan IAM Condition ke resource Agent Platform Sessions:
- Menetapkan akses IAM bersyarat di level project: `resourcemanager.projects.setIamPolicy`
Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.
Jika berencana menggunakan IAM Conditions di seluruh organisasi, Anda juga memerlukan izin untuk mengelola kebijakan organisasi.
Membuat akses bersyarat untuk sesi
Berikan akses bersyarat ke sesi dengan menambahkan kondisi ke binding kebijakan Identity and Access Management di level project. Kondisi ini menggunakan fungsi api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") untuk memeriksa ID pengguna resource sesi. Anda menentukan ID pengguna saat
membuat sesi.
Untuk panduan mendetail tentang cara membuat kebijakan IAM dengan kondisi, lihat Kondisi dalam kebijakan izin.
Untuk memberikan satu peran ke akun utama, lakukan hal berikut:
Konsol
Di konsol Google Cloud , buka halaman IAM.
Pilih project Anda.
Pilih principal yang akan diberi peran:
Untuk memberikan peran kepada akun utama yang sudah memiliki peran lain pada resource, temukan baris yang berisi akun utama, klik Edit akun utama di baris tersebut, dan klik Tambahkan peran lain.
Untuk memberikan peran ke agen layanan, pilih kotak centang Sertakan pemberian peran yang disediakan Google untuk melihat alamat emailnya.
Untuk memberikan peran kepada akun utama yang belum memiliki peran pada resource, klik Berikan Akses, lalu masukkan ID akun utama. Misalnya,
my-user@example.comatau//iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
Pilih peran yang akan diberikan dari menu drop-down. Untuk praktik keamanan terbaik, pilih peran yang hanya menyertakan izin yang diperlukan oleh akun utama Anda. Anda dapat memilih salah satu peran IAM Sesi khusus.
Tambahkan kondisi ke peran, menggunakan
aiplatform.googleapis.com/sessionUserIdsebagai atribut API. Lihat contoh di bawah untuk mengetahui beberapa kemungkinan pernyataan kondisi.Klik Simpan. Akun utama diberi peran pada resource.
gcloud
-
Di konsol Google Cloud , aktifkan Cloud Shell.
Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan terbuka dan menampilkan prompt command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.
-
Perintah
add-iam-policy-bindingmemungkinkan Anda memberikan peran ke akun utama dengan cepat.Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:
-
PROJECT_ID: Project ID Google Cloud Anda. Project ID berupa alfanumerik, sepertimy-project. -
PRINCIPAL: ID untuk akun utama, atau anggota, yang biasanya memiliki bentuk berikut:PRINCIPAL_TYPE:ID. Misalnya,user:my-user@example.comatauprincipalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Untuk mengetahui daftar lengkap nilai yang dapat dimilikiPRINCIPAL, lihat ID principal.Untuk jenis akun utama
user, nama domain dalam ID harus berupa domain Google Workspace atau Cloud Identity. Untuk mempelajari cara menyiapkan domain Cloud Identity, lihat ringkasan Cloud Identity. -
ROLE_NAME: Nama peran yang ingin Anda cabut. Gunakan salah satu format berikut:- Peran bawaan:
roles/aiplatform.IDENTIFIER - Peran khusus level project:
projects/PROJECT_ID/roles/IDENTIFIER
Pilih peran yang akan diberikan dari menu drop-down. Untuk praktik keamanan terbaik, pilih peran yang hanya menyertakan izin yang diperlukan oleh akun utama Anda. Anda dapat memilih salah satu peran IAM Sesi khusus.
- Peran bawaan:
-
CONDITION: Tambahkan kondisi ke peran, menggunakanaiplatform.googleapis.com/sessionUserIdsebagai atribut API. Lihat contoh di bawah untuk mengetahui beberapa kemungkinan pernyataan kondisi.
Jalankan perintah berikut:
Linux, macOS, atau Cloud Shell
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=PRINCIPAL --role=ROLE_NAME \ --condition=CONDITION
Windows (PowerShell)
gcloud projects add-iam-policy-binding PROJECT_ID ` --member=PRINCIPAL --role=ROLE_NAME ` --condition=CONDITION
Windows (cmd.exe)
gcloud projects add-iam-policy-binding PROJECT_ID ^ --member=PRINCIPAL --role=ROLE_NAME ^ --condition=CONDITION
Respons berisi kebijakan IAM yang telah diupdate.
-
Terraform
Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi penyedia Terraform.
Jika menggunakan Terraform untuk menetapkan kebijakan IAM, Anda dapat menyertakan kondisi dalam resource google_project_iam_member untuk membatasi akses anggota ke sesi.
resource "google_project_iam_member" "example" { project = "PROJECT_ID" role = "ROLE" member = "MEMBER" condition { title = "Session Access Condition" description = "IAM condition for Session" expression = "CONDITION" } }
Ganti variabel berikut:
-
PROJECT_ID: Project ID Google Cloud Anda. Project ID berupa alfanumerik, sepertimy-project. -
ROLE: Peran IAM yang akan diberikan, misalnya,roles/aiplatform.sessionEditor. -
MEMBER: Akun utama yang akan diberi peran, misalnya,user:developerA@corp.com. Untuk mengetahui daftar lengkap nilai yang dapat dimilikiMEMBER, lihat ID principal. -
CONDITION: IAM Condition Anda menggunakanaiplatform.googleapis.com/sessionUserIdsebagai atribut API. Lihat contoh di bawah untuk mengetahui beberapa kemungkinan pernyataan kondisi.
Praktik terbaik untuk izin tingkat ID Pengguna
Saat Anda membuat kondisi untuk sesi, gunakan praktik terbaik berikut:
Gunakan peran IAM Sesi khusus: Kondisi IAM Sesi hanya boleh digunakan untuk peran yang berlaku untuk sesi dan Peristiwa sesi. Anda dapat menggunakan peran khusus seperti
aiplatform.googleapis.com/sessionViewer,aiplatform.googleapis.com/sessionEditor, danaiplatform.googleapis.com/sessionUseruntuk mencegah akses yang terlalu permisif. Lihat bagian Peran IAM Sesi Khusus untuk mengetahui detail selengkapnya.Gunakan kondisi positif: Sebaiknya gunakan kondisi positif (seperti pemeriksaan kesetaraan atau keberadaan awalan) pada
aiplatform.googleapis.com/sessionUserIduntuk akurasi yang lebih tinggi. Karena jenis dan layanan yang tidak didukung diwakili oleh ID pengguna kosong, kondisi negatif (seperti pemeriksaan ketidaksetaraan) mungkin secara tidak sengaja cocok dengan berbagai resource, yang dapat terlalu permisif dan memungkinkan pemberian izin yang tidak terduga.Persingkat kondisi jika memungkinkan: Sebaiknya gunakan logika yang paling singkat dan paling sederhana dalam ekspresi IAM Condition, terutama jika Anda berencana memiliki banyak kondisi. Kebijakan izin IAM memiliki batasan ukuran, dan menyederhanakan kondisi akan mencegah terjadinya batasan IAM. Lihat Batasan untuk mengetahui detail selengkapnya. Misalnya, Anda dapat menyederhanakan pemeriksaan dua ID pengguna yang berbeda dengan menggabungkan pernyataan gabungan:
api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB'karena pernyataan ini dievaluasi ke hasil yang sama dengan pernyataan yang lebih singkatapi.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].
Peran IAM Sesi Khusus
Sangat penting untuk mencegah kebijakan IAM yang terlalu permisif saat menggunakan IAM Conditions. Tabel berikut mencantumkan peran khusus yang dapat Anda gunakan saat memberikan peran IAM bersyarat untuk API sesi:
| Nama Peran | Deskripsi | Izin yang Disertakan |
|---|---|---|
roles/aiplatform.sessionViewer |
Memberikan akses hanya baca ke sesi dan peristiwa listingan. |
|
roles/aiplatform.sessionEditor |
Memberikan akses tulis ke sesi dan menambahkan peristiwa. |
|
roles/aiplatform.sessionUser |
Memberikan akses penuh ke sesi dan acara, termasuk semua izin pelihat dan editor. |
Mencakup semua izin sessionEditor dan
sessionViewer.
|
Menggunakan IAM Conditions dengan Sesi
Bagian ini membahas contoh penggunaan IAM Conditions dengan Sesi berikut:
Memberikan akses baca ke sesi dengan pencocokan ID pengguna yang sama persis.
Memberikan akses tulis ke sesi yang berisi awalan tertentu di ID pengguna.
Memberikan akses penuh ke sesi yang berisi salah satu dari dua ID pengguna.
Memberikan akses baca ke sesi dengan ID pengguna yang sama persis
Kondisi berikut memberi individu userA@gmail.com akses lihat hanya
ke sesi yang memiliki ID pengguna persis userA.
Artinya, individu tersebut memiliki kemampuan untuk mendapatkan sesi dan mencantumkan
peristiwa sesi, asalkan ID pengguna sama persis dengan userA. Pengguna tidak memiliki akses ke sesi dengan ID pengguna seperti userB.
{ "members": ["user:userA@gmail.com"], "role": "roles/aiplatform.sessionViewer", "condition": { "title": "Session Access Condition", "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'userA'" } }
Memberikan akses tulis ke sesi yang berisi awalan tertentu di ID pengguna
Kondisi berikut memberi individu developerA@corp.com akses edit
ke sesi apa pun yang berisi ID pengguna yang diawali dengan user. Anda dapat menggunakan
startsWith untuk pemeriksaan awalan dan endsWith untuk pemeriksaan akhiran.
Artinya, developer memiliki kemampuan untuk membuat, memperbarui, dan menghapus
sesi, serta menambahkan peristiwa, dengan ID pengguna seperti userA atau
user1234.
{ "members": ["user:developerA@corp.com"], "role": "roles/aiplatform.sessionEditor", "condition": { "title": "Session Access Condition", "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')" } }
Memberikan akses penuh ke sesi yang berisi salah satu dari dua ID pengguna
Kondisi berikut memberi pengguna grup group:engineering@corp.com
(pelihat dan editor) akses ke sesi yang hanya memiliki ID pengguna userA atau
user123.
{ "members": ["group:engineering@corp.com"], "role": "roles/aiplatform.sessionUser", "condition": { "title": "Session Access Condition", "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']" } }
Batasan
Batas akun utama: Kebijakan IAM dibatasi hingga 1.500 akun utama unik. Batas ini dapat dikelola menggunakan grup Google. Lihat selengkapnya di Batasan pada semua akun utama.
Dukungan
ListSessionsAPI: ListSessions API tidak mendukung kondisi IAM. Untuk memberikan izin ListSessions, Anda harus memberikan peran tanpa syarat kepada akun utama, sepertiaiplatform.googleapis.com/sessionViewer,aiplatform.googleapis.com/sessionUser, atau peran Gemini Enterprise Agent Platform tanpa syarat yang relevan.