View a markdown version of this page

Menulis kebijakan dalam bahasa alami - Batuan Dasar Amazon AgentCore
Gambaran umumContohEfek kebijakanSemantik otorisasiElemen kebijakanContoh kebijakanSintaks kondisiMenggabungkan kondisiPerangkap umum

Menulis kebijakan dalam bahasa alami

Kebijakan di AgentCore akan secara otomatis memilih wilayah optimal dalam geografi Anda untuk memproses permintaan inferensi Anda yang dibuat melalui layanan pembuat Kebijakan. Ini memaksimalkan sumber daya komputasi yang tersedia, ketersediaan model, dan memberikan pengalaman pelanggan terbaik. Data Anda akan tetap disimpan hanya di wilayah tempat permintaan berasal, namun, permintaan input dan hasil keluaran dapat diproses di luar wilayah tersebut. Semua data akan dikirimkan dienkripsi di seluruh jaringan aman Amazon.

Kebijakan dalam AgentCore akan secara aman merutekan permintaan inferensi Anda ke sumber daya komputasi yang tersedia dalam wilayah geografis tempat permintaan tersebut berasal, sebagai berikut:

  • Permintaan inferensi yang berasal dari Uni Eropa akan diproses di dalam Uni Eropa.

  • Permintaan inferensi yang berasal dari Amerika Serikat akan diproses di Amerika Serikat.

  • Permintaan inferensi yang berasal dari APAC akan diproses dalam APAC.

Gambaran umum

Cedar menyediakan kontrol akses yang tepat, tetapi membutuhkan pembelajaran sintaks formal. NL2cedar memungkinkan Anda untuk:

  1. Tulis persyaratan otorisasi dalam bahasa alami

  2. Secara otomatis mengkonversi ke sintaks Cedar

  3. Verifikasi kebijakan yang dihasilkan sesuai dengan kebutuhan Anda

catatan

Pembuatan kebijakan bahasa alami memerlukan AgentCore Gateway dan mesin kebijakan yang diterapkan. Layanan ini menggunakan skema AgentCore Gateway untuk menghasilkan kebijakan Cedar yang valid. Lihat Memulai Kebijakan AgentCore untuk petunjuk penyiapan.

catatan

Bahasa alami fleksibel, tetapi presisi sangat penting untuk keamanan. Kebijakan harus jelas dan tidak ambigu.

Contoh

Kebijakan pengembalian dana dari bagian sebelumnya dapat dinyatakan dalam bahasa alami:

Bahasa alami:

Izinkan prinsipal dengan nama pengguna “agen pengembalian uang” untuk memproses pengembalian dana ketika jumlah pengembalian dana kurang dari $500.

Konversi ke Cedar: 

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"RefundTool___process_refund",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/refund-gateway"
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "refund-agent" &&
  context.input.amount < 500
};

Efek kebijakan

Kebijakan otorisasi memiliki dua kemungkinan efek: izin dan larangan.

Kebijakan izin

Kebijakan izin menentukan apa yang dapat dilakukan pengguna:

  • “Izinkan agen pengembalian dana pengguna untuk memproses pengembalian uang”

  • “Izinkan pengguna dengan direktur peran untuk menyetujui keputusan”

  • “Otorisasi pengguna dengan admin lingkup: tulis untuk memperbarui cakupan”

Melarang kebijakan

Kebijakan larangan menentukan apa yang tidak dapat dilakukan pengguna:

  • “Blokir pengguna dari mengakses model sensitivitas tinggi”

  • “Tolak penjamin emisi junior dari menyetujui keputusan”

  • “Melarang pengguna memproses pengembalian uang saat validasi risiko tertunda”

Semantik otorisasi

Memahami bagaimana Cedar mengevaluasi kebijakan sangat penting untuk menulis aturan otorisasi yang efektif. Cedar mengikuti tiga prinsip dasar:

  • Secara default, semuanya ditolak - Jika tidak ada kebijakan yang secara eksplisit mengizinkan suatu tindakan, kebijakan tersebut akan diblokir secara otomatis

  • Melarang selalu menang - Jika ada kebijakan larangan yang cocok, akses ditolak meskipun kebijakan izin juga cocok

  • Setidaknya satu izin diperlukan - Agar akses diberikan, setidaknya satu kebijakan izin harus cocok DAN tidak ada kebijakan larangan yang dapat cocok

Mengapa menggunakan kebijakan larangan jika semuanya ditolak secara default?

Kebijakan melarang memastikan bahwa tindakan tertentu tidak dapat secara keliru diizinkan. Bahkan jika seseorang menulis kebijakan izin yang lebih luas, kebijakan larangan diutamakan dan memblokir akses.

Contoh skenario: 

// Broad permit policy - allows all users to view model results
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"ModelAPI___view_results",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/model"
);

// Forbid policy - blocks access to high-sensitivity results
forbid(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"ModelAPI___view_results",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/model"
)
when {
  context.input.sensitivity == "high"
};

Hasil: Pengguna dapat melihat hasil sensitivitas rendah dan sedang (izin berlaku), tetapi hasil sensitivitas tinggi selalu diblokir (melarang kemenangan).

Gunakan kebijakan larangan untuk:

  • Pembatasan keamanan eksplisit yang tidak boleh diganti

  • Persyaratan kepatuhan

  • Penutupan darurat

  • Membuat pengecualian untuk kebijakan izin yang lebih luas

Elemen kebijakan

Kebijakan otorisasi memerlukan tiga elemen kunci:

  1. Siapa - Pengguna atau peran mana yang dapat melakukan tindakan

  2. Apa - Operasi atau alat apa yang dapat mereka gunakan

  3. Kapan - Dalam kondisi atau kendala apa

Spesifikasi utama

Prinsipal mengidentifikasi pengguna, peran, atau grup mana yang berlaku untuk kebijakan tersebut.

Ekspresi fleksibel:

  • “Izinkan agen pengembalian uang pengguna untuk...”

  • “Izinkan pengguna dengan agen pengembalian uang nama pengguna untuk...”

  • “Pengguna dengan peran agen asuransi dapat...”

  • “Siapa pun dengan ruang lingkup pengembalian uang: tulis diizinkan untuk...”

  • “Semua pengguna bisa...”

Jadilah spesifik tentang identitas:

Tidak lengkap: ❌ “Izinkan pemrosesan pengembalian uang di bawah $500"

Selesai: ✓ “Izinkan agen pengembalian uang untuk memproses pengembalian uang di bawah $500"

Spesifikasi tindakan

“Apa” mengidentifikasi operasi, alat, atau tindakan mana yang dikendalikan kebijakan.

Kata kerja aksi fleksibel:

  • “Izinkan pengguna untuk memproses pengembalian uang”

  • “Izin pemrosesan pengembalian uang”

  • “Pengguna dapat membuat aplikasi”

  • “Otorisasi melihat log audit”

Lebih spesifik tentang alat ini:

Vague: ❌ “Izinkan pengguna mengakses model”

Hapus: ✓ “Izinkan tim ilmu data mengakses model analitik”

Spesifikasi kondisi

“Kapan” menentukan dalam keadaan apa kebijakan tersebut berlaku.

Ekspresi kondisional yang fleksibel:

  • “... ketika jumlahnya kurang dari $500"

  • “... jika wilayahnya AS, CA, atau Inggris”

  • “... hanya ketika status persetujuan disetujui oleh manajer”

  • “... asalkan skor risiko telah diserahkan”

Tepat dengan kondisi:

Vague: ❌ “Izinkan transfer jika jumlahnya masuk akal”

Tepat: ✓ “Izinkan transfer ketika jumlahnya kurang dari $10.000"

Contoh kebijakan

Contoh berikut menunjukkan bagaimana menyusun kebijakan bahasa alami dengan prinsip, tindakan, dan kondisi yang jelas.

Contoh 1: User-Based Kebijakan Sederhana

Izinkan agen pengembalian dana pengguna untuk memproses pengembalian dana ketika jumlahnya kurang dari $500.

Elemen:

  • Siapa: agen pengembalian dana pengguna

  • Apa: pengembalian dana proses

  • Kapan: jumlahnya kurang dari $500

Contoh 2: Role-Based dengan Beberapa Kondisi

Memungkinkan pengguna dengan agen asuransi peran untuk memperbarui cakupan ketika jenis pertanggungan adalah kewajiban atau tabrakan dan kebijakan aktif.

Elemen:

  • Siapa: pengguna dengan agen asuransi peran

  • Apa: perbarui cakupan

  • Kapan: Jenis pertanggungan adalah kewajiban atau tabrakan DAN kebijakan aktif

Contoh 3: Scope-Based Akses

Izinkan pengguna dengan cakupan perjalanan: pesan untuk membuat pemesanan penerbangan ketika wilayah tersebut bukan UE dan produk memenuhi syarat.

Elemen:

  • Siapa: pengguna dengan ruang lingkup perjalanan:buku

  • Apa: buat pemesanan penerbangan

  • Kapan: wilayah bukan UE DAN produk memenuhi syarat

Contoh 4: Semua Orang dengan Kendala

Izinkan semua pengguna untuk melihat hasil model ketika sensitivitas data rendah atau sedang dan jenis hasilnya adalah skor risiko.

Elemen:

  • Siapa: semua pengguna

  • Apa: lihat hasil model

  • Kapan: sensitivitas data rendah atau sedang DAN tipe hasilnya adalah skor risiko

Sintaks kondisi

Kondisi adalah di mana kebijakan sering menjadi ambigu. Berikut cara menulis kondisi yang jelas dan dapat diuji.

Perbandingan Numerik

Contoh yang bagus:

  • “ketika jumlahnya kurang dari $500"

  • “ketika jumlah pertanggungan di bawah 5 juta”

  • “ketika klaim melebihi $10.000.000"

  • “ketika jumlah penumpang tepat 2"

Hindari istilah yang tidak jelas:

  • ❌ “ketika jumlahnya kecil”

  • ❌ “ketika cakupannya tinggi”

Pencocokan String

Pertandingan yang tepat:

  • “ketika wilayahnya adalah AS”

  • “ketika metode pembayarannya adalah kartu kredit”

  • “ketika status disetujui”

Beberapa opsi:

  • “ketika wilayahnya adalah AS atau CA atau Inggris”

  • “ketika jenis keputusan disetujui atau dirujuk”

Pencocokan pola:

  • “ketika email berisi @example .com”

  • “ketika ruang lingkup berisi admin:write”

Negasi:

  • “ketika wilayah itu bukan UE”

  • “ketika klasifikasi tidak dibatasi”

Kondisi Boolean

Pemeriksaan langsung:

  • “ketika produk memenuhi syarat”

  • “ketika skor risiko dikirimkan”

  • “ketika pengiriman ekspres diminta”

Negasi:

  • “ketika produk tidak memenuhi syarat”

  • “ketika skor risiko tidak dikirimkan”

Keberadaan Lapangan

Membutuhkan bidang:

  • “ketika ada alasan yang diberikan”

  • “ketika ID aplikasi ada”

  • “ketika tanggal pengembalian ditentukan”

Menggabungkan kondisi

Kebijakan riil seringkali membutuhkan beberapa kondisi. Gunakan konektor logis yang jelas.

DAN Logika (Semua Harus Benar)

Gunakan kata-kata seperti: “dan”, “juga”, “tambahan”, “sementara”, “dengan”

Contoh:

Izinkan aplikasi ketika wilayah tersebut adalah AS dan produk memenuhi syarat dan wilayah tersebut aktif.

ATAU Logika (Setidaknya Satu Harus Benar)

Gunakan kata-kata seperti: “atau”, “alternatifnya”, “baik”

Contoh:

Izinkan persetujuan ketika klaim melebihi $10.000.000 atau tingkat risiko tinggi atau kritis.

Logika Kompleks

Untuk kondisi kompleks, gunakan struktur yang jelas:

Contoh:

Izinkan finalisasi saat tahap alur kerja selesai ditinjau atau disetujui, dan status kepatuhan disahkan, dan wewenangnya adalah manajer atau direktur.

Perangkap umum

Hindari kesalahan umum ini saat menulis kebijakan bahasa alami untuk memastikan mereka mengonversi dengan benar ke sintaks Cedar.

Kesalahan 1: Prinsipal Samar-samar

Buruk: “Izinkan akses ke alat pengembalian dana”

Bagus: “Izinkan agen pengembalian dana pengguna untuk mengakses alat pengembalian dana”

Kesalahan 2: Tindakan Ambigu

Buruk: “Izinkan pengguna mengakses data”

Bagus: “Izinkan pengguna untuk melihat catatan pasien”

Kesalahan 3: Kondisi Subyektif

Buruk: “Izinkan transfer ketika jumlahnya masuk akal”

Bagus: “Izinkan transfer ketika jumlahnya kurang dari $10.000"

Kesalahan 4: Kondisi Hilang

Buruk: “Izinkan pengguna dengan admin lingkup: tulis untuk memperbarui cakupan”

Bagus: “Izinkan pengguna dengan admin lingkup: tulis untuk memperbarui cakupan saat kebijakan aktif dan jenis cakupan adalah kewajiban atau tabrakan”

Kesalahan 5: Logika Tidak Jelas

Buruk: “Izinkan ketika A atau B dan C”

Bagus: “Izinkan kapan (A atau B) dan C” atau “Izinkan saat A atau (B dan C)”