View a markdown version of this page

Fine-grained kontrol akses untuk Memori - Batu Dasar Amazon AgentCore
Cara kerja kontrol akses halusSiapkan kontrol akses halus untuk MemoriTindakan memori dan atribut permintaanApa yang dapat Anda terapkanMengadopsi kontrol akses halus pada Memori yang adaHubungan dengan opsi kontrol akses lainnya

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Fine-grained kontrol akses untuk Memori

Dengan kontrol akses berbutir halus (FGAC) untuk Amazon Bedrock AgentCore Memory, Anda dapat mengikat akses Memori ke identitas pem OAuth-authenticated anggil.

Saat pemanggil mencapai Memori dengan kredentif AWS IAM, Anda sudah dapat membatasi akses berdasarkan tindakan, berdasarkan sumber daya Memori, dan berdasarkan cakupan aktor, sesi, dan namespace permintaan, menggunakan kebijakan berbasis identitas dan berbasis sumber daya IAM dengan kunci kondisi Memori. Untuk kontrol tersebut, lihat Organisasi AgentCore memori di Memori dan Resource-based kebijakan untuk Amazon Bedrock AgentCore.

Kontrol IAM tersebut cocok dengan prinsip IAM yang memanggil Memori. Mereka tidak dapat mengekspresikan aturan yang dikunci pada OAuth/JWT identitas, karena pen OAuth-authenticated elepon bukan kepala sekolah IAM. Ini penting untuk aplikasi di mana pemanggil melakukan otentikasi dengan OAuth daripada AWS kredensial—misalnya, aplikasi agen yang pengguna akhirnya masuk melalui penyedia OpenID Connect. Dalam arsitektur itu pemanggil HTTP biasanya agen atau backend, yang melewati JWT pengguna akhir (atau agen sendiri) dengan setiap permintaan; FGAC mengevaluasi kebijakan terhadap identitas dalam token itu. Dengan FGAC, Anda dapat menulis kebijakan yang membandingkan atribut permintaan dengan klaim token, sehingga Anda dapat menerapkan aturan seperti:

  • Seorang penelepon hanya dapat mengakses acara di mana permintaan sama actorId dengan klaim JWT sub mereka.

  • Seorang pemanggil hanya dapat mengambil catatan memori di bawah namespace yang dibawa dalam klaim token mereka sendiri.

  • Akses diberikan hanya kepada penelepon yang menyajikan O client_id Auth tertentu.

Kebijakan FGAC juga dapat mengkondisikan tindakan yang sama Memory-resource, dan cakupan atribut permintaan yang ditawarkan IAM, sehingga kebijakan tunggal dapat menggabungkan siapa pemanggil dengan operasi dan data mana yang dapat mereka akses.

FGAC untuk Memori diimplementasikan dengan Kebijakan di Amazon Bed AgentCore rock. Anda melampirkan mesin kebijakan ke gateway yang berada di depan sumber daya Memori Anda dan menulis kebijakan di Cedar, bahasa kebijakan sumber terbuka yang didokumentasikan di situs web Kebijakan Cedar. Gateway mengevaluasi kebijakan ini sebelum meneruskan permintaan ke Memori. Bahasa kebijakan Cedar, tipe utama, mesin kebijakan, dan validasi kebijakan semuanya didokumentasikan dalam Kebijakan di Amazon Bedrock AgentCore — halaman ini hanya menjelaskan apa yang khusus untuk Memori: tindakan dan atribut permintaan yang diekspos konektor Memori, dan pola kebijakan yang mengisolasi data Memori berdasarkan pemanggil.

catatan

FGAC untuk Memori dibangun di atas konektor AgentCore Memori. Siapkan gateway dengan target konektor Memori terlebih dahulu. Untuk informasi selengkapnya, lihat Mengakses AgentCore Memori melalui gateway.

Topik

Cara kerja kontrol akses halus

Mesin kebijakan menyimpan serangkaian kebijakan Cedar dan mengevaluasinya untuk setiap permintaan yang mengalir melalui gateway terkait. Setelah gateway mengotentikasi pemanggil dan menyelesaikan permintaan ke operasi Memori, mesin kebijakan mengevaluasi kebijakan terhadap prinsipal permintaan (siapa yang memanggil), tindakan (operasi Memori), sumber daya (gateway mana), dan konteks (atribut permintaan, seperti parameter jalur dan bidang isi). Evaluasi dibantah secara default dan diganti. forbid permit

Karena konektor Memori membuat setiap operasi Memori tersedia sebagai tindakan Cedar dengan bidang permintaannya, kebijakan Anda dapat mengizinkan atau menolak operasi Memori tertentu dan kondisi pada atribut permintaan mereka. Model Cedar generik — struktur kebijakan,permit/forbid, AgentCore::OAuthUser dan jenis AgentCore::IamEntity utama, tag, dan context.input — dijelaskan dalam Mem ahami kebijakan Cedar dan konsep Inti.

Siapkan kontrol akses halus untuk Memori

catatan

Anda dapat mengatur kontrol akses halus untuk Memori melalui AWS Management Console, AWS SDK, dan AWS Command Line Interface (AWS CLI).

Setelah Anda memiliki gateway dengan target konektor Memori (lihat AgentCore Mem ori Akses melalui gateway):

  1. Buat mesin kebijakan dan tambahkan kebijakan Cedar Anda. Untuk langkah-langka hnya, lihat Membuat mesin kebijakan dan Membuat kebijakan. Untuk kebijakan yang harus ditulis, lihat Contoh kebijakan untuk Memori.

  2. Kaitkan mesin kebijakan dengan gateway yang berada di depan sumber daya Memori Anda, dengan menyetel gatewaypolicyEngineConfiguration. Anda dapat mengaturnya saat membuat gateway dengan CreateGateway, atau menambahkannya nanti dengan UpdateGateway.

Mesin kebijakan mode mengontrol apakah kebijakan diberlakukan (ENFORCE) atau hanya dievaluasi dan dicatat tanpa memblokir lalu lintas (LOG_ONLY). Uji kebijakan Anda LOG_ONLY sebelum beralih ke ENFORCE untuk menghindari penolakan yang tidak diinginkan. Untuk mode penegakan, validasi kebijakan, dan pengujian, lihat Memvalidasi dan menguji kebijakan dan Kebijakan penggunaan.

Tindakan memori dan atribut permintaan

Bagian ini adalah Memory-specific referensi untuk menulis kebijakan: id tindakan Cedar untuk setiap operasi Memori, dan atribut permintaan yang tersedia di bawahcontext.input.

ID tindakan memori

Setiap operasi Memori adalah tindakan Cedar bernama<target-name>___<METHOD>:<uri-template>, di <target-name> mana nama target konektor Anda. URI menyimpan placeholder parameter path-nya — mereka tidak diganti dengan nilai konkret. Dalam tabel berikut, ganti <target-name> dengan nama target konektor Anda.

Operasi memori ID tindakan cedar

ListEvents

<target-name>___POST:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}

CreateEvent

<target-name>___POST:/memories/{memoryId}/events

GetEvent

<target-name>___GET:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}

DeleteEvent

<target-name>___DELETE:/memories/{memoryId}/actor/{actorId}/sessions/{sessionId}/events/{eventId}

ListSessions

<target-name>___POST:/memories/{memoryId}/actor/{actorId}/sessions

ListActors

<target-name>___POST:/memories/{memoryId}/actors

RetrieveMemoryRecords

<target-name>___POST:/memories/{memoryId}/retrieve

ListMemoryRecords

<target-name>___POST:/memories/{memoryId}/memoryRecords

GetMemoryRecord

<target-name>___GET:/memories/{memoryId}/memoryRecord/{memoryRecordId}

DeleteMemoryRecord

<target-name>___DELETE:/memories/{memoryId}/memoryRecords/{memoryRecordId}

ListMemoryExtractionJobs

<target-name>___POST:/memories/{memoryId}/extractionJobs

StartMemoryExtractionJob

<target-name>___POST:/memories/{memoryId}/extractionJobs/start

Action-id wildcard tidak didukung; untuk memberikan beberapa operasi dalam satu kebijakan, daftarkan denganaction in […​].

catatan

Operasi batch Memori (BatchCreateMemoryRecords,BatchUpdateMemoryRecords, danBatchDeleteMemoryRecords) tidak tersedia sebagai tindakan Cedar dan tidak dapat diatur oleh kontrol akses yang halus. Masing-masing membawa beberapa catatan dalam satu permintaan, yang tidak dapat dievaluasi oleh mesin kebijakan secara individual — sehingga kondisi per rekaman atau per namespace tidak dapat diterapkan padanya.

Anda masih dapat mengizinkan atau menolak operasi batch secara keseluruhan dengan kebijakan berbasis identitas dan berbasis sumber daya IAM (misalnya, dengan mengizinkan atau menolak tindakan tersebut). bedrock-agentcore:BatchCreateMemoryRecords Yang hilang hanyalah perincian per rekaman: pada lapisan kontrol akses berbutir halus, operasi batch adalah segalanya atau tidak sama sekali.

Minta bidang konteks

Gateway mengekspos atribut setiap permintaan di bawahcontext.input, menggabungkan parameter jalur dan bidang isi permintaan. Jagalah setiap bidang has sebelum Anda membacanya (misalnya,context has input && context.input has actorId).

Parameter jalur (dari URI):

  • context.input.memoryId

  • context.input.actorId

  • context.input.sessionId

  • context.input.eventId

  • context.input.memoryRecordId

Request-body bidang (tergantung operasi, dari payload permintaan):

  • context.input.namespace

  • context.input.namespacePath

  • context.input.metadata

  • context.input.filter

  • context.input.payload

  • dan bidang tubuh lainnya yang ditentukan oleh skema masing-masing operasi

Bidang yang tersedia berbeda berdasarkan operasi. Bidang yang dibawa oleh satu operasi (misalnya, actorId aktifListEvents) mungkin tidak ada pada operasi lain yang cocok dengan kebijakan yang sama.

Awas

Kebijakan yang mereferensikan bidang konteks divalidasi terhadap skema untuk tindakan dalam cakupannya, tetapi tidak terhadap setiap operasi yang mungkin dicapai permintaan saat runtime. Jika kebijakan mereferensikan bidang yang tidak dibawa oleh permintaan masuk, kebijakan dapat dibuat dengan sukses dan menjangkauACTIVE, namun menolak permintaan dengan 403 respons saat mesin kebijakan mengevaluasinya, karena bidang yang direferensikan tidak ada. Kondisi ini tidak dilaporkan saat Anda membuat kebijakan.

Untuk menghindari penolakan yang tidak terduga:

  • Cakup setiap kebijakan ke tindakan tertentu yang permintaannya membawa bidang referensi kebijakan, dan konfirmasikan bidang tersebut terhadap setiap operasi di tabel ID tindakan memori.

  • Jagalah setiap akses lapangan dengan has (misalnya,context has input && context.input has actorId) sehingga suatu permit kondisi dapat dievaluasi secara dapat diprediksi ketika bidang tidak ada.

  • Uji kebijakan dalam LOG_ONLY mode sebelum menegakkannya, sehingga Anda dapat mengamati hasil evaluasi tanpa menolak lalu lintas langsung. Untuk informasi selengkapnya, lihat Men yiapkan kontrol akses berbutir halus untuk Memori.

Apa yang dapat Anda terapkan

Penegakan FGAC melalui konektor Memori tersedia di semua mode otentikasi masuk gateway. Menggunakan tindakan dan atribut di atas, Anda dapat menerapkan:

  • Principal-type gating — kebijakan yang dicakup oleh atau pen IAM-only elep OAuth-only on cocok atau ditolak oleh kelas pemanggil.

  • Per-identity isolasi — atribut permintaan seperti yang actorId dapat diperlukan untuk menyamai sub klaim pengguna atau agen yang diautentikasi di JWT, memungkinkan pemilik dan menolak orang lain.

  • Isolasi namespace — membandingkan permintaan namespace atau namespacePath terhadap literal, atau terhadap jalur namespace yang dibawa dalam klaim token, membatasi catatan mana yang dapat diambil oleh pemanggil.

  • Pelingkup an tindakan — tindakan tunggal, serangkaian tindakan, atau tindakan apa pun dapat diizinkan; tindakan yang tidak diizinkan ditolak.

  • Path-parameter kondisi — parameter jalur sepertimemoryId,actorId, dansessionId.

  • Request-body kondisi — bidang tubuh seperti metadata dannamespacePath.

  • Penjepitan sumber daya — ARN gateway yang cocok diizinkan; ARN yang berbeda ditolak.

  • Kondisi klaim JWT — klaim token seperti sub dan akses client_id gerbang (OAuth inbound).

  • Kondisi identitas IAM — IAM ARN penelepon dapat dicocokkan dengan pola (IAM inbound).

Untuk kebijakan yang menerapkan ini, lihat Contoh kebijakan untuk Memori.

Mengadopsi kontrol akses halus pada Memori yang ada

Pola isolasi utama mensyaratkan bahwa permintaan sama dengan sub klaim JWT penelepon ()context.input.actorId == principal.getTag("sub"). actorId Penerapan yang ada sering menggunakan id pengguna internal karena tidak actorId cocok dengan sub nilai dari penyedia identitas mereka. Jika actorId nilai-nilai Anda sudah sama dengan penyedia Andasub, tidak ada perubahan yang diperlukan. Jika tidak, pilih salah satu pendekatan berikut:

Cocokkan pada klaim JWT khusus

Jika penyedia identitas Anda dapat mengeluarkan klaim yang sudah memegang id pengguna internal Anda (misalnya, klaim khusus yang mencerminkan actorId skema Anda), bandingkan dengan klaim tersebut, sub bukan — misalnya,context.input.actorId == principal.getTag("custom:app_user_id"). Jagalah dengan hasTag dulu. Ini menghindari perubahan data yang disimpan.

Isolasi dengan namespace alih-alih actorId

Jika catatan memori jangka panjang Anda diatur ke dalam ruang nama per pengguna, terapkan isolasi pada namespace daripada aktif. actorId Mintalah penyedia identitas Anda mengeluarkan klaim yang menyimpan jalur namespace lengkap pemanggil, dan bandingkan permintaan dengan klaim namespacePath tersebut. Untuk pola isolasi namespace, lihat Contoh kebijakan untuk Mem ori.

Sejajarkan actorId dengan sub

Jika Anda ingin menggunakan actorId == sub pola default, migrasikan peristiwa dan catatan baru untuk menggunakan penyedia sub sebagaiactorId. Karena AgentCore Memory menyimpan peristiwa dan catatan di bawah yang actorId Anda berikan, ini biasanya berlaku ke depan daripada menulis ulang data historis; rencanakan untuk periode transisi di mana kedua skema mungkin ada.

Tip

Anda dapat memvalidasi salah satu pendekatan ini tanpa mempengaruhi lalu lintas langsung dengan melampirkan kebijakan dalam LOG_ONLY mode terlebih dahulu dan meninjau log evaluasi. Lihat Men yiapkan kontrol akses berbutir halus untuk Memori.

Hubungan dengan opsi kontrol akses lainnya

Kebijakan Cedar yang dievaluasi oleh mesin kebijakan adalah lapisan otorisasi per-permintaan yang sadar identitas untuk lalu lintas Memori melalui gateway. Mereka melengkapi, dan dapat dikombinasikan dengan, opsi kontrol akses gateway lainnya: