View a markdown version of this page

Keamanan dalam pembayaran Amazon Bedrock AgentCore - Batuan Dasar Amazon AgentCore

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

Keamanan dalam pembayaran Amazon Bedrock AgentCore

Praktik terbaik berikut dapat membantu Anda mencegah insiden keamanan saat menggunakan pembayaran Amazon Bedrock AgentCore . Kontrol pencegahan menghentikan tindakan yang tidak aman sebelum terjadi. Kontrol Detektif memunculkan aktivitas tak terduga sehingga Anda dapat menanggapinya.

Kontrol pencegahan

Gunakan kontrol ini untuk membatasi apa yang dapat dilakukan agen Anda dan untuk menjaga materi sensitif dari jangkauannya.

Menegakkan hak istimewa paling sedikit dengan pola IAM lima peran

AgentCore pembayaran memisahkan bidang kontrol dari bidang data dengan menggunakan peran IAM yang berbeda. Siapkan izin IAM berdasarkan persona yang cocok dengan setiap peran. Dengan pola ini, tidak ada peran tunggal yang dapat menaikkan anggaran dan membelanjakannya untuk melawannya.

# Peran Tujuan

1

ControlPlaneRole

Mengelola layanan.

2

ManagementRole

Mengkonfigurasi sesi. Peran ini secara eksplisit ditolak. ProcessPayment

3

ProcessPaymentRole

Mengeksekusi pembayaran.

4

ResourceRetrievalRole

Service-assumed. Mengambil sesi dan status kredensi.

5

AWSMarketplaceManageSubscriptions(padaControlPlaneRole)

Untuk Coinbase, berlangganan akun ke daftar Marketplace. Kebijakan AWS terkelola pada administrator, bukan peran yang dapat diasumsikan terpisah.

Untuk informasi selengkapnya, lihat peran IAM untuk AgentCore pembayaran.

Simpan kredensi di Identitas AgentCore

Jangan pernah menyematkan kredensi penyedia dompet dalam kode agen atau variabel lingkungan.

  • Simpan kredensyal Coinbase CDP atau Stripe (Privy) sebagai in Identity. PaymentCredentialProvider AgentCore

  • Layanan mengambilnya saat runtime dengan menggunakan. ResourceRetrievalRole

  • Putar kredensil pada jadwal yang direkomendasikan penyedia dompet. Jika kredensi dikompromikan, segera cabut.

  • Untuk konektor Coinbase yang dibuat dengan Quick create, kredensialnya dikelola layanan. Putar dengan RotatePaymentConnectorCredentials alih-alih menghasilkan kunci di Platform Pengembang Coinbase. Untuk informasi lebih lanjut, lihat bagian selanjutnya.

Untuk informasi selengkapnya, lihat AgentCore Identitas.

Putar kredenal konektor yang dikelola layanan

Saat Anda membuat konektor Coinbase dengan Quick create, AgentCore pembayaran mengeluarkan kunci API CDP Coinbase dan rahasia Dompet untuk Anda dan menyimpannya sebagai penyedia kredensi pembayaran di AgentCore Identity, yang menyimpan materi rahasia di Secrets Manager. AWS Karena layanan memiliki kredensil ini, Anda dapat menggantinya sesuai permintaan denganRotatePaymentConnectorCredentials, tanpa masuk ke Platform Pengembang Coinbase atau menangani materi utama sendiri.

Konektor memiliki dua rahasia yang dikelola layanan, dan Anda memutar masing-masing untuk alasan yang berbeda. Putar kunci API sebagai pemeliharaan rutin. Putar rahasia Dompet hanya ketika dikompromikan atau hilang. Untuk informasi selengkapnya, lihat Memilih kredensil mana yang akan diputar.

catatan

Anda dapat memutar kredensyal dari konsol, AWS CLI, dan SDK. AWS AgentCore CLI dan AgentCore SDK tidak menyediakan perintah rotasi, jadi gunakan salah satu dari tiga lainnya.

Periksa apakah konektor memenuhi syarat

Rotasi hanya berlaku untuk konektor yang kredensialnya dikelola oleh layanan. provisionModeBidang konektor memberi tahu Anda kasus mana Anda berada di:

provisionMode Cara memutar

QUICK_CREATE

Amazon Bedrock AgentCore menyediakan kredensialnya, sehingga dapat dikelola dengan layanan. Panggil RotatePaymentConnectorCredentials.

MANUAL

Anda memberikan kredensialnya, jadi Anda memilikinya. Putar mereka dengan penyedia pembayaran terlebih dahulu, lalu panggil UpdatePaymentCredentialProvider dengan nilai baru.

GetPaymentConnectordan ListPaymentConnectors kembali provisionMode dan merupakan sumber otoritatif untuk itu. GetPaymentConnectorjuga mengembalikancredentialsUpdatedAt, stempel waktu saat kredenal yang dikelola layanan konektor saat ini mulai berlaku. Layanan menyemai stempel waktu ini dengan waktu penyediaan awal dan memperbaruinya pada setiap rotasi. Gunakan untuk melacak usia kredensi. Itu tidak ada untuk MANUAL konektor.

Di konsol, provisionMode muncul sebagai kolom Jenis pembuatan, yang menunjukkan Quick Create atau Manual. Anda dapat menemukannya di tempat-tempat berikut:

  • Pada halaman Pembayaran, perluas baris Manajer Pembayaran untuk mencantumkan konektornya, lalu periksa kolom Jenis pembuatan untuk konektor.

  • Pada halaman detail Manajer Pembayaran, di bagian Konektor pembayaran, periksa kolom Jenis pembuatan.

  • Pada halaman detail konektor, di bagian Autentikasi pembayaran, periksa Jenis pembuatan. Bagian ini juga menunjukkan tanggal rotasi kredenal terakhir, yang setara dengan konsol. credentialsUpdatedAt

Pilih kredenal mana yang akan diputar

Untuk konektor CDP Coinbase, credentialsToRotate bawa coinbaseCDP anggota dengan salah satu atau kedua rahasia berikut. Kedua rahasia melayani tujuan yang berbeda dan membawa risiko yang berbeda, jadi putar secara terpisah dan untuk alasan yang berbeda.

Rahasia Kapan harus memutarnya Apa pengaruhnya

API_KEY

Putar ID kunci API Coinbase CDP dan rahasia kunci API sebagai pemeliharaan rutin, pada jadwal reguler, dan segera jika Anda curiga bahwa kunci tersebut terpapar.

Kunci API mengautentikasi permintaan ke Coinbase. Amazon Bedrock AgentCore mendaftarkan kunci pengganti sebelum menghapus yang sebelumnya, sehingga pemrosesan pembayaran tidak terganggu.

WALLET_SECRET

Putar rahasia Dompet hanya jika dikompromikan atau hilang. Ini bukan bagian dari perawatan rutin.

Rahasia Wallet menandatangani operasi penulisan dompet, jadi memutarnya memengaruhi penandatanganan transaksi. Coinbase menggantikan rahasia Wallet di tempatnya daripada menambahkan yang kedua, jadi harapkan hingga satu menit selama ProcessPayment panggilan bisa gagal. Proyek CDP Coinbase memiliki satu rahasia Dompet, sehingga rotasi memengaruhi setiap konektor yang menggunakan proyek yang sama.

Rotasi menggantikan rahasia pada penyedia kredensi pembayaran konektor. Setiap konektor yang menggunakan autentikasi pembayaran yang sama terpengaruh, tidak hanya konektor yang Anda beri nama dalam permintaan.

Cara kerja rotasi

Rotasi sinkron. Operasi menyelesaikan rotasi sebelum mengembalikan respons, dan hanya memutar satu set kredensil pada satu waktu untuk konektor tertentu. Ketika sebuah rahasia berhasil berputar, rahasia baru segera berlaku dan konektor tetap dalam READY keadaan. Ketika sebuah rahasia gagal diputar, responsnya menyertakan kesalahan dan rahasia menyimpan nilainya saat ini. Anda dapat mencoba kembali permintaan tersebut.

Respons mengembalikan pengidentifikasi konektor, nya status (yang READY setelah rotasi berhasil), danlastUpdatedAt:

{ "paymentManagerId": "<paymentManagerId>", "paymentConnectorId": "<paymentConnectorId>", "status": "READY", "lastUpdatedAt": "2025-11-04T18:22:41.507000+00:00" }

Setelah rotasi, panggil GetPaymentConnector dan konfirmasikan bahwa credentialsUpdatedAt lanjutan. Kemudian ganti salinan rahasia sebelumnya yang Anda gunakan di luar Amazon Bedrock AgentCore.

RotatePaymentConnectorCredentialsadalah idempoten. Berikan clientToken ketika Anda ingin mencoba ulang permintaan dengan aman, misalnya dari pekerjaan rotasi otomatis. Mencoba lagi dengan token yang sama mengembalikan hasil rotasi asli alih-alih mengeluarkan rahasia lain.

Putar kunci API

Putar kunci API sebagai pemeliharaan rutin. Amazon Bedrock AgentCore mendaftarkan kunci pengganti dengan Coinbase sebelum menghapus yang sebelumnya, sehingga pemrosesan pembayaran berlanjut saat rotasi berjalan.

contoh
Console
  1. Buka AgentCore konsol Amazon Bedrock.

  2. Di panel navigasi, di bawah Build, pilih Pembayaran.

  3. Pilih Manajer Pembayaran yang memiliki konektor. Di bagian Konektor pembayaran, pilih konektor.

  4. Pada halaman detail konektor, pilih Rotate credentials, lalu pilih Rotate API secrets.

    catatan

    Rotate credentials hanya muncul untuk konektor yang dibuat dengan Quick create. Jika konektor menggunakan kredensyal yang Anda berikan, putar dengan Coinbase sebagai gantinya. Untuk informasi selengkapnya, lihat Periksa apakah konektor memenuhi syarat.

  5. Di kotak dialog Rotate API secrets, tinjau peringatan tersebut. Rotasi menghapus rahasia API saat ini dan membuat yang baru dengan menggunakan akun Coinbase yang Anda tautkan dengan autentikasi pembayaran ini. Semua konektor yang menggunakan autentikasi pembayaran ini juga terpengaruh.

  6. Pilih Putar. Konsol menampilkan pesan bahwa rotasi dapat memakan waktu hingga satu menit. Ketika rotasi selesai, pesan sukses mengonfirmasi bahwa rahasia API telah diputar.

AWS CLI

Konfirmasikan bahwa konektor memenuhi syarat, dan perhatikan credentialsUpdatedAt nilainya saat ini:

aws bedrock-agentcore-control get-payment-connector \ --payment-manager-id <paymentManagerId> \ --payment-connector-id <paymentConnectorId> \ --region us-east-1

Putar kunci API:

aws bedrock-agentcore-control rotate-payment-connector-credentials \ --payment-manager-id <paymentManagerId> \ --payment-connector-id <paymentConnectorId> \ --credentials-to-rotate '{"coinbaseCDP": {"secrets": ["API_KEY"]}}' \ --region us-east-1
AWS SDK
import boto3 client = boto3.client("bedrock-agentcore-control", region_name="us-east-1") connector = client.get_payment_connector( paymentManagerId="<paymentManagerId>", paymentConnectorId="<paymentConnectorId>" ) # Rotation applies only to connectors with service-managed credentials. if connector.get("provisionMode") != "QUICK_CREATE": raise RuntimeError( "This connector uses credentials that you provided. Rotate them with the " "payment provider, and then call update_payment_credential_provider." ) response = client.rotate_payment_connector_credentials( paymentManagerId="<paymentManagerId>", paymentConnectorId="<paymentConnectorId>", credentialsToRotate={"coinbaseCDP": {"secrets": ["API_KEY"]}} ) print(f"Status: {response['status']}") print(f"Rotation completed at: {response['lastUpdatedAt']}")

Putar rahasia Dompet

Putar rahasia Dompet hanya jika dikompromikan atau hilang. Proyek CDP Coinbase menyimpan satu rahasia Dompet dan Coinbase menggantinya, sehingga rotasi memengaruhi penandatanganan transaksi untuk setiap konektor yang menggunakan proyek CDP Coinbase yang sama.

penting

Harapkan waktu henti hingga satu menit untuk ProcessPayment API saat rahasia Wallet berputar. Rencanakan rotasi untuk periode aktivitas pembayaran rendah, dan pastikan agen Anda menangani pembayaran yang gagal dengan anggun.

contoh
Console
  1. Buka AgentCore konsol Amazon Bedrock.

  2. Di panel navigasi, di bawah Build, pilih Pembayaran.

  3. Pilih Manajer Pembayaran yang memiliki konektor. Di bagian Konektor pembayaran, pilih konektor.

  4. Pada halaman detail konektor, pilih Rotate credentials, lalu pilih Rotate wallet secrets.

  5. Di kotak dialog Putar rahasia dompet, tinjau peringatannya. Rotasi menghapus rahasia Dompet saat ini dan membuat yang baru dengan menggunakan akun Coinbase yang Anda tautkan dengan autentikasi pembayaran ini. Semua konektor yang menggunakan autentikasi pembayaran ini juga terpengaruh. Harapkan waktu henti hingga satu menit untuk ProcessPayment API.

  6. Pilih Putar. Konsol menampilkan pesan bahwa rotasi dapat memakan waktu hingga satu menit. Ketika rotasi selesai, pesan sukses mengonfirmasi bahwa rahasia Wallet diputar.

AWS CLI
aws bedrock-agentcore-control rotate-payment-connector-credentials \ --payment-manager-id <paymentManagerId> \ --payment-connector-id <paymentConnectorId> \ --credentials-to-rotate '{"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}}' \ --region us-east-1

Konfirmasikan bahwa pembayaran berhasil setelah rotasi, karena rahasia Wallet menandatangani setiap operasi penulisan dompet.

AWS SDK
response = client.rotate_payment_connector_credentials( paymentManagerId="<paymentManagerId>", paymentConnectorId="<paymentConnectorId>", credentialsToRotate={"coinbaseCDP": {"secrets": ["WALLET_SECRET"]}} ) print(f"Status: {response['status']}") print(f"Rotation completed at: {response['lastUpdatedAt']}")

Putar kedua rahasia dalam satu permintaan

Anda juga dapat membuat daftar kedua rahasia dalam satu permintaan. Amazon Bedrock AgentCore kemudian memutarnya satu demi satu dalam permintaan yang sama, dimulai dengan kunci API dan diikuti oleh rahasia Wallet. Pertimbangan downtime yang sama untuk rahasia Wallet berlaku.

Karena dua rotasi berjalan secara berurutan, kegagalan di tengah jalan dapat membuat kunci API sudah diputar sementara rahasia Wallet menyimpan nilainya saat ini. Respons melaporkan kesalahan. Coba lagi permintaan untuk menyelesaikan rahasia yang tersisa.

Untuk menjaga kedua rotasi tetap independen, kirim permintaan terpisah untuk setiap rahasia. Inilah yang dilakukan konsol.

contoh
AWS CLI
aws bedrock-agentcore-control rotate-payment-connector-credentials \ --payment-manager-id <paymentManagerId> \ --payment-connector-id <paymentConnectorId> \ --credentials-to-rotate '{"coinbaseCDP": {"secrets": ["API_KEY", "WALLET_SECRET"]}}' \ --region us-east-1
AWS SDK
response = client.rotate_payment_connector_credentials( paymentManagerId="<paymentManagerId>", paymentConnectorId="<paymentConnectorId>", credentialsToRotate={ "coinbaseCDP": {"secrets": ["API_KEY", "WALLET_SECRET"]} } )

Kesalahan

Kesalahan Penyebab

ValidationException

Permintaan tidak berlaku untuk konektor ini. Ini termasuk memilih rahasia yang tidak digunakan konektor, melewati daftar rahasia kosong, dan memanggil operasi pada konektor yang kredensialnya Anda berikan sendiri.

ConflictException

Rotasi sudah berjalan untuk konektor ini, atau konektor tidak dalam keadaan yang menerima rotasi. Tunggu konektor kembali READY dan coba lagi.

ResourceNotFoundException

Manajer pembayaran atau konektor pembayaran tidak ada di akun dan AWS Wilayah ini.

AccessDeniedException

Penelepon tidak berwenang untuk memanggil RotatePaymentConnectorCredentials manajer pembayaran. Lihat peran IAM untuk AgentCore pembayaran.

ThrottlingException

Permintaan itu dibatasi. Coba lagi dengan backoff eksponensial.

Untuk skema permintaan dan respons lengkap, lihat RotatePaymentConnectorCredentialsdi Referensi API.

Atur UserId header dengan benar

Pada manajer pembayaran otorisasi IAM-configured masuk, backend Anda menegaskan X-Amzn-Bedrock-AgentCore-Payments-User-Id header, dan AgentCore pembayaran tidak memverifikasinya. Anda bertanggung jawab untuk menetapkan nilai ini dengan benar.

AgentCore pembayaran memverifikasi pemanggil IAM dan JWT (saat menggunakan OAuth), tetapi kebenaran header pada panggilan API adalah tanggung jawab Anda. UserId Jangan biarkan pengguna akhir atau agen mempengaruhi header ini secara langsung.

Penerapan multi-penyewa yang aman

Untuk penerapan multi-penyewa yang melayani beberapa pengguna akhir, gunakan jenis otorisasi CUSTOM_JWT (OAuth) di pengelola pembayaran. Ini memberikan layanan dengan identitas pengguna akhir yang diverifikasi. Dengan manajer IAM-configured pembayaran, AgentCore pembayaran tidak memverifikasi identitas pengguna akhir.

Pendanaan dan delegasi adalah dua keputusan pengguna akhir yang terpisah, dan keduanya dibuat out-of-band dari agen:

  • Pendanaan — Pengguna akhir menyetor dana melalui portal penyedia dompet. Agen tidak memiliki akses API ke pendanaan dan tidak boleh meminta atau memulai secara otomatis.

  • Delegasi — Pengguna akhir memberikan izin melalui Izin Pengeluaran Coinbase atau Tindakan Delegasi Privy. Jangan menganggap delegasi bersifat permanen, karena pengguna dapat mencabutnya kapan saja. Tangani delegasi yang dicabut dengan anggun.

Menjaga agen terisolasi dari instrumen pembayaran

Agen tidak boleh mengakses nomor kartu, nilai CVV, detail bank, atau kunci pribadi dompet. Pandangan agen berhenti pada “izin untuk membelanjakan dari dompet milik pengguna.”

  • Kunci dompet dipegang oleh penyedia dalam penahanan sendiri—bukan oleh atau pengembang. AWS

  • Jangan pernah melewatkan detail instrumen pembayaran melalui petunjuk, input alat, atau jendela konteks.

Akses alat lingkup dengan Kebijakan di AgentCore

Untuk otorisasi tingkat alat, paparkan titik akhir berbayar melalui Amazon Bedrock Gateway. AgentCore Setiap panggilan melalui Gateway dicegat oleh Policy in AgentCore, Cedar-based mesin yang mengevaluasi permintaan—termasuk identitas agen, nama alat, dan parameter—dan memutuskan apakah akan mengizinkannya.

Sesi kebijakan dan pembayaran mencakup keputusan yang berbeda:

  • Kebijakan mengontrol siapa yang memanggil alat mana dengan parameter apa.

  • Sesi pembayaran mengontrol berapa banyak yang dapat dihabiskan dan untuk berapa lama.

Bersama-sama, mereka memberi Anda tuas ortogonal untuk akses alat dan jumlah pengeluaran.

  • Tulis kebijakan Cedar yang dicakup oleh identitas agen, grup pengguna, dan parameter permintaan.

  • Tolak akses ke alat berbiaya tinggi untuk agen yang tidak membutuhkannya.

  • Tinjau dan audit kebijakan secara teratur saat katalog alat Anda berubah.

Untuk informasi selengkapnya, lihat Kebijakan di AgentCore.

Gunakan sesi pembayaran dengan batas anggaran dan TTL

Setiap pembayaran berjalan dalam sesi pembayaran yang memiliki jumlah pengeluaran maksimum dan waktu kedaluwarsa. Lapisan infrastruktur memberlakukan batas-batas ini, sehingga injeksi cepat dan model non-determinisme tidak dapat menimpanya.

  • Atur maxSpendAmount ke minimum yang diperlukan untuk tugas tersebut, dan atur TTL pendek.

  • Mulailah dengan anggaran konservatif dan naikkan hanya karena agen terbukti dapat diandalkan.

  • Penandatanganan yang gagal secara otomatis mengembalikan pengurangan anggaran.

Untuk informasi selengkapnya, lihat Membuat sesi pembayaran.

Validasi dan batasi alamat PayTo

payToAlamat menentukan dompet penerima. AgentCore pembayaran tidak memberlakukan payTo pembatasan sisi server, jadi aplikasi Anda harus memvalidasi alamat sebelum memanggil API. ProcessPayment

  • Pertahankan daftar izin alamat pedagang yang telah diverifikasi sebelumnya, dan tolak alamat yang tidak dikenal.

  • Jangan biarkan model menghasilkan alamat PayTo. Mereka harus berasal dari sumber tepercaya, seperti permintaan pembayaran x402 atau registri terverifikasi.

  • Validasi terhadap pedagang yang diharapkan saat memproses respons x402.

  • Lebih suka AgentCore Gateway untuk penemuan titik akhir, karena menyediakan payTo alamat terverifikasi melalui Bazaar x402.

  • Terapkan kebijakan Cedar untuk membatasi alamat mana yang dapat dibayar agen.

  • Jangan cache alamat di seluruh sesi. Selalu gunakan alamat yang disediakan merchant saat ini, yang divalidasi terhadap allowlist Anda.

  • Skrining penerima. Batas sesi terikat berapa banyak agen dapat menghabiskan, bukan siapa yang dapat membayar. Gunakan kebijakan dompet untuk menolak pembayaran ke penerima tertentu. Untuk Stripe (Privy), ikuti penyaringan sanksi untuk panduan pembayaran di situs web Privy. Coinbase secara otomatis menyaring semua transaksi terhadap daftar sanksi OFAC.

  • Gunakan kebijakan penyedia pembayaran untuk membatasi tindakan dompet seperti penandatanganan dan transfer. Untuk informasi lebih lanjut, lihat dokumentasi kebijakan Stripe (Privy) di situs web Privy dan dokumentasi keamanan dan kebijakan Coinbase di situs web Coinbase.

Akses jaringan yang aman

  • Gunakan titik akhir VPC untuk menjaga lalu lintas dari internet publik.

  • Menerapkan kebijakan endpoint dan kondisi IAM (aws:sourceVpc,aws:sourceVpce) untuk membatasi asal.

  • Aktifkan AWS CloudTrail untuk semua panggilan API AgentCore pembayaran.

Desain untuk kegagalan pembayaran dan rollback

  • Menerapkan idempotensi untuk mencegah pembayaran duplikat pada percobaan ulang.

  • Menangani kegagalan pembayaran dengan perilaku fallback yang jelas. Jangan mencoba lagi tanpa batas waktu.

  • Pantau kegagalan sebagian dan terapkan transaksi kompensasi.

Kontrol detektif

Gunakan kontrol ini untuk mengamati aktivitas pembayaran dan anomali permukaan sehingga Anda dapat menanggapinya.

Aktifkan observabilitas dan pencatatan audit

AgentCore pembayaran menyediakan observabilitas otomatis melalui Amazon CloudWatch:

  • Vending logs — Setiap panggilan data plane dicatat (siapa, apa, berapa banyak, dan kepada siapa).

  • Rentang vended - Jejak siklus hidup pembayaran penuh tersedia di. AWS X-Ray

  • Tetapkan alarm untuk pola pengeluaran anomali, seperti pembayaran ke alamat yang tidak terdaftar, jumlah penerima yang berbeda yang luar biasa besar, atau perubahan alamat mendadak untuk pedagang yang dikenal.

  • Simpan log sesuai dengan persyaratan kepatuhan Anda.

  • Jangan mengandalkan kode agen untuk mencatat tindakannya sendiri.

Untuk informasi selengkapnya, lihat Observabilitas dengan Amazon CloudWatch.

Tinjau konfigurasi secara teratur

  • Audit anggaran dan kurangi batas untuk agen yang meremehkan.

  • Tinjau kebijakan Cedar dan peran IAM setiap tiga bulan.

  • Pantau dasbor penyedia dompet untuk pendelegasian atau aktivitas pendanaan yang tidak terduga.