Mengontrol akses ke Sesi dengan IAM Conditions

Secara default, izin Identity and Access Management sesi berada di tingkat project. Dokumen ini menjelaskan cara menggunakan Kondisi IAM untuk mengontrol akses yang lebih terperinci ke resource Sesi Vertex AI Agent Engine.

Ringkasan

Dengan IAM Conditions, Anda dapat memberikan akses ke resource sesi dan peristiwa 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 tingkat project dan berlaku untuk semua sesi dan peristiwa sesi dalam project. Anda dapat menerapkan kondisi IAM ke semua jenis prinsipal, termasuk pengguna project dan akun layanan Anda.

Kondisi IAM berguna untuk memberikan izin Identity and Access Management (IAM) ke banyak resource sesi terkait secara bersamaan, termasuk yang belum ada. Anda dapat membatasi akses ke sesi dan peristiwa sehingga pengguna hanya dapat mengakses informasinya 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: Pahami 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 di organisasi Anda yang harus menerima izin tertentu. Misalnya, pertimbangkan hal berikut:
- Haruskah pengguna dapat melihat sesi pengguna lain?
- Haruskah developer dapat melihat semua sesi?
- Haruskah administrator project dapat melihat semua sesi?
- Haruskah identitas agen tertentu dapat mengakses sesi tertentu?
Berikan peran IAM: Pastikan Anda memiliki peran yang diperlukan yang berisi izin yang diperlukan untuk melakukan tugas dalam dokumen ini.
Guna mendapatkan izin yang Anda perlukan untuk menerapkan Kondisi IAM ke resource Sesi Vertex AI Agent Engine, minta administrator Anda untuk memberi Anda peran IAM berikut:
- Untuk project: Admin IAM Project (`roles/resourcemanager.projectIamAdmin`)
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menerapkan Kondisi IAM ke resource Sesi Vertex AI Agent Engine. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:
Izin yang diperlukan

Izin berikut diperlukan untuk menerapkan Kondisi IAM ke resource Sesi Vertex AI Agent Engine:
- Menetapkan akses IAM bersyarat di tingkat 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 tingkat project. Kondisi ini menggunakan fungsi api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") untuk memeriksa ID pengguna dari 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.

Buka IAM
Pilih project Anda.
Pilih principal yang akan diberi peran:
- Untuk memberikan peran kepada principal yang sudah memiliki peran lain pada resource, temukan baris yang memuat principal tersebut, klik Edit principal di baris tersebut, dan klik Tambahkan peran lain.
  
  Untuk memberikan peran kepada agen layanan, pilih kotak centang Sertakan pemberian peran yang disediakan Google untuk melihat alamat emailnya.
  
  Catatan: Anda tidak dapat mengedit peran yang diwariskan saat mengelola akses ke resource. Untuk mengedit peran yang diwariskan, buka resource tempat peran diberikan.
- Untuk memberikan peran kepada principal yang belum memiliki peran pada resource, klik Berikan Akses, lalu masukkan ID principal—misalnya, my-user@example.com atau //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/sessionUserId sebagai atribut API. Lihat contoh di bawah untuk mengetahui beberapa kemungkinan pernyataan kondisi.
Klik Simpan. Akun utama diberi peran pada resource.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Perintah add-iam-policy-binding memungkinkan 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, seperti my-project.
- PRINCIPAL: ID untuk akun utama, atau anggota, yang biasanya memiliki bentuk berikut: PRINCIPAL_TYPE:ID. Misalnya, user:my-user@example.com atau principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Untuk mengetahui daftar lengkap nilai yang dapat dimiliki PRINCIPAL, 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.
- CONDITION: Tambahkan kondisi ke peran, menggunakan aiplatform.googleapis.com/sessionUserId sebagai 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, seperti my-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 dimiliki MEMBER, lihat ID principal.
CONDITION: Pernyataan kondisi IAM Anda menggunakan aiplatform.googleapis.com/sessionUserId sebagai 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, dan aiplatform.googleapis.com/sessionUser untuk 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/sessionUserId untuk akurasi yang lebih baik. 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.
Perpendek ketentuan jika memungkinkan: Sebaiknya gunakan logika terpendek dan tersederhana dalam ekspresi ketentuan IAM Anda, terutama jika Anda berencana memiliki banyak ketentuan. Kebijakan 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 majemuk: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB' karena menghasilkan hasil yang sama dengan pernyataan yang lebih pendek api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Peran IAM Sesi Khusus

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.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Memberikan akses tulis ke sesi dan menambahkan peristiwa.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	Memberikan akses penuh ke sesi dan peristiwa, termasuk semua izin pelihat dan editor.	Mencakup semua izin `sessionEditor` dan `sessionViewer`.

Menggunakan IAM Conditions dengan Sesi

Bagian ini membahas contoh penggunaan Kondisi IAM dengan Sesi berikut:

Memberikan akses baca ke sesi dengan kecocokan ID pengguna yang tepat.
Memberi 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 kecocokan ID pengguna yang persis

Kondisi berikut memberikan akses lihat userA@gmail.com kepada individu hanya untuk sesi yang memiliki ID pengguna userA yang sama persis.

Artinya, individu tersebut dapat mengambil sesi dan mencantumkan peristiwa sesi, selama ID pengguna persis 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 memberikan akses edit developerA@corp.com kepada individu untuk sesi apa pun yang berisi ID pengguna yang dimulai 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 memberikan akses kepada grup pengguna group:engineering@corp.com (pelihat dan editor) 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 API ListSessions: ListSessions API tidak mendukung kondisi IAM. Untuk memberikan izin ListSessions, Anda harus memberikan peran tanpa syarat kepada prinsipal, seperti aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser, atau peran Vertex AI tanpa syarat yang relevan.