Mengontrol akses ke Memory Bank dengan IAM Conditions

Secara default, izin Identity and Access Management memori berada di level project. Dokumen ini menjelaskan cara menggunakan IAM Conditions untuk mengontrol akses yang lebih terperinci ke resource Bank Memori Vertex AI Agent Engine.

Ringkasan

Dengan IAM Conditions, Anda dapat memberikan akses ke resource memori dan revisi memori hanya jika kondisi tertentu terpenuhi. Anda dapat mengontrol akses ke kenangan berdasarkan kolom scope dalam resource kenangan menggunakan atribut API "aiplatform.googleapis.com/memoryScope" dengan ekspresi yang ditulis dalam Common Expression Language. Cakupan adalah kamus arbitrer yang disediakan saat membuat atau menghasilkan kenangan, seperti {'user_id': '123'}, yang memungkinkan Anda mengatur kenangan mana yang termasuk dalam grup mana.

Kebijakan Identity and Access Management bersyarat ini dibuat di tingkat project dan berlaku untuk semua kenangan 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 Memory Bank terkait secara bersamaan, termasuk yang belum ada. Anda dapat membatasi akses ke kenangan dan revisi Anda sehingga pengguna hanya dapat mengakses informasi mereka sendiri, atau sehingga developer hanya dapat melihat resource Bank Memori tertentu tanpa pemberian izin khusus.

Sebelum memulai

Untuk menyiapkan kebijakan IAM bersyarat untuk kenangan dan revisi kenangan, lakukan hal berikut:

Tinjau IAM Conditions: Pahami ringkasan IAM Conditions.
Tentukan peran yang diperlukan: Identifikasi peran IAM Memory Bank 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:
- Apakah developer harus dapat melihat semua kenangan.
- Apakah administrator project dapat melihat semua kenangan.
- Apakah identitas agen tertentu hanya dapat mengakses kenangan 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 Bank Memori Vertex AI Agent Engine, minta administrator Anda 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 bawaan ini berisi izin yang diperlukan untuk menerapkan Kondisi IAM ke resource Bank Memori 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 Bank Memori Agent Engine Vertex AI:
- 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 kenangan

Akses bersyarat ke kenangan diberikan dengan menambahkan kondisi ke binding kebijakan IAM di tingkat project. Kondisi ini menggunakan fungsi api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) untuk memeriksa peta cakupan resource memori. Anda menentukan cakupan saat membuat atau membuat kenangan.

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 Bank Memori khusus.
Tambahkan kondisi ke peran, menggunakan aiplatform.googleapis.com/memoryScope 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 Bank Memori khusus.
- CONDITION: Tambahkan kondisi ke peran, menggunakan aiplatform.googleapis.com/memoryScope 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 kenangan.

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    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.memoryEditor.
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/memoryScope sebagai atribut API. Lihat contoh di bawah untuk mengetahui beberapa kemungkinan pernyataan kondisi.

Praktik terbaik untuk izin tingkat cakupan

Saat Anda membuat kondisi untuk Memory Bank, gunakan praktik terbaik berikut:

Gunakan peran Bank Memori khusus: Kondisi IAM Bank Memori hanya boleh digunakan untuk peran yang berlaku untuk memori dan revisi memori. Anda dapat menggunakan peran khusus seperti aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor, dan aiplatform.googleapis.com/memoryUser untuk mencegah akses yang terlalu permisif. Lihat peran IAM Bank Memori Khusus untuk mengetahui detail selengkapnya.
Gunakan kondisi positif: Sebaiknya gunakan kondisi positif (seperti pemeriksaan kesetaraan atau keberadaan key-value pair) pada aiplatform.googleapis.com/memoryScope untuk akurasi yang lebih tinggi. Karena jenis dan layanan yang tidak didukung diwakili oleh cakupan 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 izin IAM memiliki batasan ukuran, dan menyederhanakan kondisi mencegah terjadinya batasan IAM ini. Lihat Batasan untuk mengetahui detail selengkapnya. Misalnya, Anda dapat menghilangkan pemeriksaan keberadaan tombol dalam ekspresi 'user_id' in "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' karena menghasilkan hasil yang sama dengan pernyataan yang lebih pendek api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Peran IAM Bank Memori 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 Memory Bank API:

Nama Peran	Deskripsi	Izin yang Disertakan
`roles/aiplatform.memoryViewer`	Memberikan akses hanya baca ke kenangan dan revisi kenangan.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	Memberikan akses tulis dan buat ke kenangan dan akses rollback ke revisi kenangan.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	Memberikan akses penuh ke kenangan dan revisi, termasuk semua izin pelihat dan editor.	Mencakup semua izin `memoryEditor` dan `memoryViewer`.

Menggunakan IAM Conditions dengan Memory Bank

Bagian ini membahas contoh berikut tentang penggunaan Kondisi IAM dengan Memory Bank:

Memberikan akses baca ke kenangan dengan kecocokan cakupan persis.
Memberikan akses tulis ke kenangan dengan cakupan yang berisi key-value pair tertentu.
Memberikan akses penuh ke kenangan dengan cakupan yang berisi kunci tertentu.
Memberikan akses penuh ke kenangan dengan cakupan yang berisi awalan tertentu.
Memberikan akses penuh ke kenangan dengan cakupan kunci dengan serangkaian nilai yang diizinkan.

Memberikan akses baca ke kenangan dengan pencocokan cakupan persis

Kondisi berikut memberikan akses lihat userA@gmail.com kepada individu hanya ke kenangan yang memiliki cakupan persis {"userId": "userA"}.

Artinya, anggota memiliki kemampuan untuk mendapatkan dan mengambil kenangan, beserta mencantumkan dan mendapatkan revisi kenangan tersebut, selama cakupannya persis {"userId": "userA"}. Pengguna tidak memiliki akses ke kenangan dengan cakupan seperti {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

Memberikan akses tulis ke kenangan dengan cakupan yang berisi key-value pair tertentu

Kondisi berikut memberikan akses pengeditan developerA@corp.com kepada individu untuk semua kenangan yang berisi key-value pair 'userId': 'userA'.

Artinya, pengguna memiliki kemampuan untuk membuat, memperbarui, menghapus, dan membuat kenangan, serta membuat dan mengembalikan revisi kenangan tersebut, dengan cakupan seperti {'userId': 'userA'} dan {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

Memberikan akses penuh ke kenangan dengan cakupan yang berisi kunci tertentu

Kondisi berikut memberikan akses pengguna grup group:engineering@corp.com (pelihat dan editor) ke kenangan yang memiliki kunci 'admin_override' atau 'public_access_flag'.

Artinya, anggota grup memiliki akses baca dan tulis penuh ke kenangan dengan cakupan seperti {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'}, dan {'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

Memberikan akses penuh ke kenangan dengan cakupan yang berisi awalan tertentu

Kondisi berikut memberikan akses kepada pengguna grup group:engineering@corp.com (pelihat dan editor) ke kenangan yang memiliki kunci 'userId' dengan nilai yang dimulai dengan 'user'.Anda dapat menggunakan 'startsWith' untuk pemeriksaan awalan dan 'endsWith' untuk pemeriksaan akhiran.

Artinya, anggota grup memiliki akses baca dan tulis penuh ke kenangan dengan cakupan seperti {'userId': 'userA'}, {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

Memberikan akses penuh ke kenangan dengan cakupan kunci dan serangkaian nilai yang diizinkan

Kondisi berikut memberikan akses pengguna grup group:engineering@corp.com (pelihat dan editor) ke kenangan yang memiliki kunci 'userId' dengan nilai 'userA' atau 'userB'.