Gambaran umum Peran Eksekusi Gateway Peran Manajemen Sumber Daya Kapan Pembaruan Peran Diperlukan?Pemecahan masalah Contoh: Membuat Kedua Peran IAM Praktik Terbaik

AgentCore Gateway dan Kebijakan dalam AgentCore Izin IAM

Panduan ini memberikan izin IAM yang diperlukan untuk menggunakan Amazon Bedrock AgentCore Gateway dengan Kebijakan AgentCore untuk kontrol otorisasi berbutir halus menggunakan kebijakan Cedar.

Gambaran umum

Saat mengintegrasikan Amazon Bedrock AgentCore Gateway dengan Policy in AgentCore, diperlukan dua peran IAM yang berbeda:

Peran Eksekusi Gateway - Peran IAM yang diasumsikan Amazon Bedrock AgentCore Gateway saat runtime untuk memanggil target dan mengevaluasi kebijakan Cedar
Peran Manajemen Sumber Daya - Peran IAM yang digunakan administrator untuk membuat dan mengelola Amazon Bedrock AgentCore Gateway dan Kebijakan dalam sumber daya AgentCore

Kedua peran melayani tujuan yang berbeda dan memerlukan izin khusus. Peran Eksekusi Gateway memerlukan izin untuk menjalankan operasi Amazon Bedrock AgentCore Gateway, sedangkan Peran Manajemen Sumber Daya memerlukan izin untuk mengonfigurasi dan mengelola Amazon Bedrock AgentCore Gateway dan Kebijakan dalam sumber daya. AgentCore

Peran Eksekusi Gateway

Peran Eksekusi Gateway diasumsikan oleh layanan Amazon Bedrock AgentCore Gateway saat memproses permintaan. Peran ini memerlukan izin untuk:

Mengevaluasi kebijakan Cedar melalui Kebijakan di AgentCore
Memanggil target seperti fungsi Lambda dan titik akhir API Gateway
Menulis log dan jejak ke CloudWatch dan X-Ray
Rahasia akses untuk konfigurasi otentikasi

penting

Peran eksekusi harus menyertakan tiga izin ini untuk menggunakan Amazon Bedrock AgentCore Gateway dengan Kebijakan di AgentCore:. bedrock-agentcore:AuthorizeAction - Mengevaluasi kebijakan Cedar untuk keputusan otorisasi. bedrock-agentcore:PartiallyAuthorizeActions - Daftar alat penelepon berwenang untuk memanggil. bedrock-agentcore:GetPolicyEngine - Mengambil konfigurasi mesin kebijakan Tanpa izin ini, Gateway tidak dapat melakukan otorisasi kebijakan. Ini bermanifestasi dalam dua cara: melampirkan Mesin Kebijakan ke Gateway yang ada akan menghasilkan InternalServerException, dan semua pemanggilan alat akan ditolak secara default bahkan jika Anda memiliki kebijakan izin yang dikonfigurasi.

Kebijakan Kepercayaan

Peran Eksekusi Gateway harus mempercayai prinsip bedrock-agentcore.amazonaws.com layanan.

penting

Ganti placeholder berikut: * us-east-1 dengan AWS Region* 123456789012 dengan ID akun AWS


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBedrockAgentCoreAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

Kebijakan Izin

Kebijakan ini memberi Amazon Bedrock AgentCore Gateway izin yang diperlukan untuk mengevaluasi kebijakan Cedar melalui Kebijakan di. AgentCore Izin dibagi menjadi dua pernyataan mengikuti prinsip hak istimewa paling sedikit.

penting

Ganti placeholder ini: * us-east-1 dengan AWS Region * 123456789012 dengan ID AWS akun* <gateway-id> dengan ID Gateway (atau gunakan* untuk semua gateway) * <policy-engine-id> dengan ID mesin kebijakan (atau gunakan* untuk semua mesin kebijakan)


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
      ]
    }
  ]
}

catatan

* Izin tambahan mungkin diperlukan tergantung pada jenis integrasi Amazon Bedrock AgentCore Gateway (misalnya, fungsi Lambda, titik akhir API Gateway). Izin ini tidak disertakan di sini karena bervariasi berdasarkan integrasi tertentu. * Untuk Produksi: Ganti placeholder dengan ID sumber daya tertentu (misalnya, policy-engine/my-policy-engine-id alih-alihpolicy-engine/<policy-engine-id>) untuk mengikuti prinsip hak istimewa paling sedikit, atau gunakan wildcard (*) untuk memungkinkan akses ke semua sumber daya jenis itu.

Peran Manajemen Sumber Daya

Peran Manajemen Sumber Daya digunakan oleh administrator untuk membuat dan mengelola Amazon Bedrock AgentCore Gateway dan Kebijakan dalam AgentCore sumber daya. Peran ini memerlukan izin untuk:

Membuat, memperbarui, dan menghapus target Gateway dan Gateway
Membuat, memperbarui, dan menghapus Policy Engine dan kebijakan Cedar
Panggil Gateway selama pembuatan kebijakan (InvokeGateway) sehingga Policy in AgentCore dapat memvalidasi tindakan dalam pernyataan Cedar terhadap kemampuan Gateway target
Teruskan Peran Eksekusi Gateway ke sumber daya Amazon Bedrock AgentCore Gateway selama pembuatan
Tag sumber daya untuk organisasi dan manajemen
Baca informasi peran IAM untuk memvalidasi konfigurasi peran eksekusi

Peran ini terpisah dari Peran Eksekusi Gateway dan hanya diperlukan saat menyiapkan atau memodifikasi Amazon Bedrock AgentCore Gateway dan Kebijakan dalam AgentCore konfigurasi.

Kebijakan Izin

penting

Ganti placeholder ini: * us-east-1 dengan AWS Region* 123456789012 dengan ID akun AWS


{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GatewayManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:DeleteGateway",
        "bedrock-agentcore:ListGateways",
        "bedrock-agentcore:InvokeGateway",
        "bedrock-agentcore:CreateGatewayTarget",
        "bedrock-agentcore:UpdateGatewayTarget",
        "bedrock-agentcore:GetGatewayTarget",
        "bedrock-agentcore:DeleteGatewayTarget",
        "bedrock-agentcore:ListGatewayTargets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    },
    {
      "Sid": "PolicyEngineManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:UpdatePolicyEngine",
        "bedrock-agentcore:GetPolicyEngine",
        "bedrock-agentcore:DeletePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:DeletePolicy",
        "bedrock-agentcore:ListPolicies"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy/*"
      ]
    },
    {
      "Sid": "PolicyGeneration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:StartPolicyGeneration",
        "bedrock-agentcore:GetPolicyGeneration",
        "bedrock-agentcore:ListPolicyGenerations",
        "bedrock-agentcore:ListPolicyGenerationAssets"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*/policy-generation/*"
      ]
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": [
        "iam:PassRole"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*BedrockAgentCore*"
      ],
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "bedrock-agentcore.amazonaws.com"
        }
      }
    },
    {
      "Sid": "IAMReadAccess",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:GetRolePolicy",
        "iam:ListAttachedRolePolicies",
        "iam:ListRolePolicies"
      ],
      "Resource": [
        "arn:aws:iam::123456789012:role/*"
      ]
    },
    {
      "Sid": "PolicyScopeManagement",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:ManageResourceScopedPolicy",
        "bedrock-agentcore:ManageAdminPolicy"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}

penting

bedrock-agentcore:InvokeGatewaydiperlukan untuk membuat atau memperbarui kebijakan Cedar, tidak hanya untuk memanggil Gateway saat runtime. CreatePolicydan UpdatePolicy memvalidasi tindakan dalam pernyataan Cedar Anda terhadap Gateway, operasi yang diotorisasi seperti InvokeGateway pada ARN Gateway. Tanpa itu, kebijakan bertransisi ke CREATE_FAILED denganInsufficient permissions to call gateway with ID <gateway-id>.

penting

ManageAdminPolicyTindakan ManageResourceScopedPolicy dan adalah gerbang khusus izin yang mengontrol jenis apa yang dapat dibuat oleh administrator kebijakan Cedar: * ManageResourceScopedPolicy - Memberikan izin untuk membuat kebijakan Cedar yang menargetkan ARN gateway tertentu (misalnya, kebijakan yang berlakugateway/my-gateway-123) * ManageAdminPolicy - Memberikan izin untuk membuat kebijakan Cedar dengan wildcard (misalnya, kebijakan yang berlaku untuk gateway/*) Kedua izin diperlukan untuk kemampuan manajemen kebijakan penuh. Ini bukan operasi API melainkan pemeriksaan otorisasi yang menentukan ruang lingkup kebijakan Cedar yang dapat dibuat melalui API Manajemen Kebijakan.

catatan

Meskipun bidang Sumber Daya disertakan untuk konsistensi, tindakan khusus izin ini terutama menggerakkan kemampuan di tingkat tindakan daripada di tingkat sumber daya.

Kapan Pembaruan Peran Diperlukan?

Tentukan apakah Kebijakan dalam AgentCore izin perlu ditambahkan ke peran eksekusi Amazon Bedrock AgentCore Gateway berdasarkan cara Amazon Bedrock AgentCore Gateway dibuat.

Skenario 1: Gateway Dibuat dengan AgentCore CLI

Status: Tindakan diperlukan

AgentCore CLI membuat peran eksekusi gateway dengan izin cakupan untuk pemanggilan target dan otentikasi keluar, tetapi tidak menyertakan Kebijakan dalam izin. AgentCore Anda harus secara manual menambahkanAuthorizeAction,PartiallyAuthorizeActions, dan GetPolicyEngine izin yang didokumentasikan dalam panduan ini ke peran eksekusi gateway.

Skenario 2: Peran Eksekusi Kustom

Status: Tindakan diperlukan

Peran IAM kustom memerlukan Kebijakan dalam AgentCore izin yang didokumentasikan dalam panduan ini untuk ditambahkan secara manual. Ikuti kebijakan izin di bagian di atas.

Skenario 3: Least-Privilege Konfigurasi Produksi

Status: Tindakan diperlukan

Untuk lingkungan produksi, cakup Kebijakan dalam AgentCore izin ke ARN sumber daya tertentu, bukan menggunakan wildcard. Ganti mesin kebijakan/* dan gateway/* dengan mesin kebijakan dan ID gateway tertentu dalam kebijakan izin Anda.

Pemecahan masalah

Bagian ini mencakup masalah umum saat mengonfigurasi izin IAM untuk Amazon Bedrock AgentCore Gateway dengan Kebijakan di. AgentCore

InternalServerException Selama Evaluasi Kebijakan

Gejala: Gateway kembali InternalServerException - Policy evaluation failed saat melampirkan Mesin Kebijakan ke Gateway yang ada, dan semua pemanggilan alat ditolak secara default bahkan dengan kebijakan izin yang dikonfigurasi.

Root Cause: Peran Eksekusi Gateway tidak memiliki Kebijakan yang diperlukan dalam AgentCore izin. Tanpa izin ini, Gateway tidak dapat melakukan otorisasi kebijakan.

Solusi: Pastikan Peran Eksekusi Gateway mencakup tiga izin ini:


{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:PartiallyAuthorizeActions",
    "bedrock-agentcore:AuthorizeAction",
    "bedrock-agentcore:GetPolicyEngine"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:policy-engine/*",
    "arn:aws:bedrock-agentcore:REGION:ACCOUNT:gateway/*"
  ]
}

catatan

Jika Anda melampirkan Mesin Kebijakan ke Gateway yang ada menggunakan konsol Mesin Kebijakan, izin IAM mungkin tidak diperbarui secara otomatis. Anda harus menambahkan izin ini secara manual ke Service-Linked Peran Gateway.

“Izin tidak cukup untuk memanggil gateway” di CreatePolicy

Gejala: CreatePolicy mengembalikanpolicyId, tetapi kebijakan kemudian bertransisi ke CREATE_FAILED with Insufficient permissions to call gateway with ID <gateway-id> — bahkan ketika Peran Eksekusi Gateway memilikiAuthorizeAction,PartiallyAuthorizeActions, danGetPolicyEngine.

Akar Penyebab: Kesenjangan ada pada Peran Manajemen Sumber Daya yang memanggilCreatePolicy, bukan Peran Eksekusi Gateway. Validasi kebijakan memanggil Gateway (diotorisasi sebagaibedrock-agentcore:InvokeGateway); kesalahan menamai Gateway tetapi perbaikannya ada pada peran pembuatan kebijakan.

Solusi: Tambahkan bedrock-agentcore:InvokeGateway (dicakup ke ARN Gateway) ke Peran Manajemen Sumber Daya:


{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:InvokeGateway"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
  ]
}

Kegagalan Diam dalam Mode LOG_ONLY

Gejala: Mesin kebijakan tampaknya bekerja dalam mode LOG_ONLY tetapi gagal secara diam-diam tanpa pesan kesalahan yang tepat.

Akar Penyebab: bedrock-agentcore:GetPolicyEngine Izin yang hilang menyebabkan kegagalan diam yang hanya muncul saat beralih ke mode ENFORCED.

Solusi: Selalu sertakan bedrock-agentcore:GetPolicyEngine dalam Peran Eksekusi Gateway, bahkan saat menggunakan mode LOG_ONLY untuk pengujian.

Mesin Kebijakan Tidak Ditemukan Kesalahan

Gejala: Amazon Bedrock AgentCore Gateway mengembalikan kesalahan yang menunjukkan tidak dapat menemukan atau mengakses mesin kebijakan.

Akar Penyebab: Kebijakan Peran Eksekusi Gateway menggunakan pola ARN yang salah atau kehilangan sumber daya mesin kebijakan.

Solusi: Pastikan ARN mesin kebijakan DAN gateway disertakan dalam array Resource:


"Resource": [
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/<policy-engine-id>",
  "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gateway-id>"
]

catatan

Keduanya AuthorizeAction dan PartiallyAuthorizeActions membutuhkan akses ke KEDUA sumber daya mesin kebijakan dan gateway.

Tips Debugging

Aktifkan CloudWatch Log - Konfigurasikan pencatatan terperinci untuk Amazon Bedrock AgentCore Gateway untuk menangkap detail evaluasi kebijakan
Tinjau X-Ray Jejak - Periksa AWS X-Ray jejak untuk mengidentifikasi di mana pemeriksaan otorisasi gagal
Mulai dengan Mode LOG_ONLY - Gunakan mode LOG_ONLY pada awalnya untuk menguji kebijakan Cedar tanpa memblokir permintaan
Verifikasi Keempat Izin - Pastikan AuthorizeActionPartiallyAuthorizeActions,, DAN semuanya GetPolicyEngine ada
Beralih ke Mode TERPAKSA - Hanya setelah memverifikasi semua izin bekerja dalam mode LOG_ONLY, beralih ke mode ENFORCED

Contoh: Membuat Kedua Peran IAM

Contoh berikut menunjukkan cara membuat kedua peran IAM yang diperlukan menggunakan CLI AWS .

Langkah 1: Buat Peran Eksekusi Gateway


# Create the trust policy file
cat > gateway-trust-policy.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}
EOF

# Create the IAM role
aws iam create-role \
  --role-name MyGatewayExecutionRole \
  --assume-role-policy-document file://gateway-trust-policy.json

Langkah 2: Lampirkan Izin ke Peran Eksekusi Gateway


# Create the permission policy file
cat > gateway-permissions.json <<EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PolicyEngineConfiguration",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetPolicyEngine"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*"
      ]
    },
    {
      "Sid": "PolicyEngineAuthorization",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:AuthorizeAction",
        "bedrock-agentcore:PartiallyAuthorizeActions"
      ],
      "Resource": [
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:policy-engine/*",
        "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/*"
      ]
    }
  ]
}
EOF

# Attach the policy to the role
aws iam put-role-policy \
  --role-name MyGatewayExecutionRole \
  --policy-name GatewayPolicyEnginePermissions \
  --policy-document file://gateway-permissions.json

catatan

Contoh ini hanya menampilkan Kebijakan dalam AgentCore izin. Izin tambahan untuk target Amazon Bedrock AgentCore Gateway (Lambda, API Gateway, dll.) harus ditambahkan berdasarkan persyaratan integrasi spesifik Anda.

Langkah 3: Langkah Selanjutnya

Setelah mengonfigurasi peran eksekusi dengan Kebijakan yang diperlukan dalam AgentCore izin, lanjutkan untuk membuat dan mengonfigurasi sumber daya Kebijakan. Untuk panduan terperinci, lihat:

Membuat Mesin Kebijakan - Lihat mesin Buat kebijakan
Menulis Kebijakan Cedar - Lihat Referensi Bahasa Kebijakan Cedar

Praktik Terbaik

Gunakan Peran Terpisah - Pertahankan peran berbeda untuk eksekusi Amazon Bedrock AgentCore Gateway dan manajemen sumber daya
Terapkan Hak Istimewa Paling Sedikit - Mulailah dengan ARN sumber daya tertentu daripada wildcard dalam produksi
Uji dengan Mode LOG_ONLY - Selalu uji integrasi mesin kebijakan dalam mode LOG_ONLY sebelum menegakkan kebijakan
Aktifkan Pemantauan - Konfigurasikan CloudWatch Log dan X-Ray penelusuran untuk pemecahan masalah dan pengamatan
Kebijakan Kontrol Versi - Simpan kebijakan Cedar dalam kontrol versi bersama kode infrastruktur
Gunakan Tag Sumber Daya - Menerapkan tag untuk mengatur dan mengelola Amazon Bedrock AgentCore Gateway dan Kebijakan dalam AgentCore sumber daya
Audit Keamanan Reguler - Meninjau kebijakan IAM secara berkala untuk memastikan kebijakan tersebut mengikuti prinsip hak istimewa yang paling sedikit

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Konsep inti

Buat mesin kebijakan