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 Izin AgentCore IAM

Panduan ini memberikan izin IAM yang diperlukan untuk menggunakan Amazon Bedrock AgentCore Gateway dengan Kebijakan AgentCore untuk kontrol otorisasi yang 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 di 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 AgentCore sumber daya.

Peran Eksekusi Gateway

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

Evaluasi kebijakan Cedar melalui Kebijakan di AgentCore
Memanggil target seperti fungsi Lambda dan titik akhir API Gateway
Tulis 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 yang dipanggil diizinkan untuk dipanggil. 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 telah mengonfigurasi kebijakan izin.

Kebijakan Kepercayaan

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

penting

Ganti placeholder berikut: * us-east-1 dengan Wil AWS ayah * 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 memberikan Amazon Bedrock AgentCore Gateway izin yang diperlukan untuk mengevaluasi kebijakan Cedar melalui Kebijakan di AgentCore. Izin dibagi menjadi dua pernyataan mengikuti prinsip hak istimewa terkecil.

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, alih- policy-engine/my-policy-engine-id alihpolicy-engine/<policy-engine-id>) untuk mengikuti prinsip hak istimewa terendah, atau gunakan wildcard (*) untuk mengizinkan akses ke semua sumber daya jenis itu.

Izin IAM untuk kebijakan temporal

Kebijakan temporal mengharuskan Gateway menyebarkan identitas sesi pemanggil di seluruh permintaan dengan mencetak Token Akses Beban Kerja (WAT). Pada aliran AWS masuk IAM, mint ini memanggil. GetWorkloadAccessToken Berikan Peran Eksekusi Gatewaybedrock-agentcore:GetWorkloadAccessToken, dicakup ke direktori identitas beban kerja Gateway. Tambahkan izin ini selain tiga izin Kebijakan (AuthorizeAction,PartiallyAuthorizeActions,GetPolicyEngine) yang sudah didokumentasikan di halaman ini. Izin ini hanya diperlukan saat kebijakan temporal aktif (ID sesi kebijakan disediakan dan Mesin Kebijakan dilampirkan); izin ini tidak diperlukan saat kebijakan temporal dinonaktifkan.

Tambahkan pernyataan berikut ke kebijakan izin Peran Eksekusi Gateway:


{
  "Sid": "PolicySessionWorkloadIdentity",
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:GetWorkloadAccessToken"
  ],
  "Resource": [
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default",
    "arn:aws:bedrock-agentcore:us-east-1:123456789012:workload-identity-directory/default/workload-identity/<gatewayId>*"
  ]
}

Tanpa izin ini, pemanggilan alat gagal pada langkah token-mint (AccessDeniedonGetWorkloadAccessToken) setelah kebijakan temporal diaktifkan. Untuk produksi, ganti <gatewayId> dengan ID Gateway tertentu untuk mengikuti prinsip-prinsip hak istimewa terendah.

Untuk ikhtisar persyaratan ini dalam konteks pertimbangan kebijakan temporal, lihat Izin IAM yang diperlukan.

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 membutuhkan 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
Menandai 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 Wil AWS ayah * 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 Gateway ARN. Tanpa itu, kebijakan beralih ke CREATE_FAILED denganInsufficient permissions to call gateway with ID <gateway-id>.

penting

Tindakan ManageResourceScopedPolicy ManageAdminPolicy dan adalah gerbang khusus izin yang mengontrol jenis kebijakan Cedar apa yang dapat dibuat administrator: * ManageResourceScopedPolicy - Memberikan izin untuk membuat kebijakan Cedar yang menargetkan ARN gateway tertentu (misalnya, kebijakan yang berlaku untukgateway/my-gateway-123) * ManageAdminPolicy - Memberikan izin untuk membuat kebijakan Cedar dengan wildcard (misalnya, kebijakan yang berlaku untuk gateway/*) Kedua izin tersebut 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

Sementara 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: T indakan 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 menambahkanAuthorizeAction,PartiallyAuthorizeActions, dan GetPolicyEngine izin yang didokumentasikan dalam panduan ini secara manual ke peran eksekusi gateway.

Skenario 2: Peran Eksekusi Kustom

Status: T indakan diperlukan

Peran IAM khusus mengharuskan 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: T indakan diperlukan

Untuk lingkungan produksi, lingkup Kebijakan dalam AgentCore izin ke ARN sumber daya tertentu daripada menggunakan wildcard. Ganti policy-engine/* 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 Policy Engine ke Gateway yang ada, dan semua pemanggilan alat ditolak secara default bahkan dengan kebijakan izin dikonfigurasi.

Akar Penyebab: 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 menyertakan tiga izin berikut:


{
  "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 Policy Engine, izin IAM mungkin tidak diperbarui secara otomatis. Anda harus menambahkan izin ini secara manual ke Service-Linked Peran Gateway.

“Izin tidak memadai untuk memanggil gateway” aktif CreatePolicy

Gejala: CreatePolicy mengembalikan apolicyId, tetapi kebijakan kemudian beralih 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 (di bedrock-agentcore:InvokeGateway otorisasi sebagai); kesalahan menamai Gateway tetapi perbaikannya ada pada peran pembuatan kebijakan.

Solusi: Tambahkan bedrock-agentcore:InvokeGateway (dicakup ke Gateway ARN) 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 DIPAKSAKAN.

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

Kesalahan Mesin Kebijakan Tidak Ditemukan

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 Sumber Daya:


"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

Kedu AuthorizeAction anya dan PartiallyAuthorizeActions memerlukan akses ke KEDUA sumber daya mesin kebijakan dan gateway.

Tips Debugging

Aktif CloudWatch kan Log - Konfigurasikan pencatatan terperinci untuk Amazon Bedrock AgentCore Gateway untuk menangkap detail evaluasi kebijakan
Tinjau X-Ray Jej ak - Periksa AWS X-Ray jejak untuk mengidentifikasi di mana pemeriksaan otorisasi gagal
Mulai dengan Mode LOG_ONLY - Gunakan mode LOG_ONLY awalnya untuk menguji kebijakan Cedar tanpa memblokir permintaan
Verifikasi Keempat Izin - AuthorizeAction PastikanPartiallyAuthorizeActions,, DAN semuanya GetPolicyEngine hadir
Beralih ke Mode DIPAK SA - Hanya setelah memverifikasi semua izin bekerja dalam mode LOG_ONLY, beralih ke mode DIPAKSA

Contoh: Membuat Kedua Peran IAM

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

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 Berikutnya

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 Membuat mesin kebijakan
Menulis Kebijakan Cedar - Lihat Referensi Bahasa Kebijakan Cedar

Praktik Terbaik

Gunakan Peran Terpisah - Pertahankan peran yang berbeda untuk eksekusi Amazon Bedrock AgentCore Gateway dan manajemen sumber daya
Terapkan Hak I stimewa Terkecil - Mulai dengan ARN sumber daya tertentu daripada wildcard dalam produksi
Uji dengan Mode LOG_ONLY - Selalu uji integrasi mesin kebijakan dalam mode LOG_ONLY sebelum menerapkan kebijakan
Aktifkan Pemantauan - Konfigur CloudWatch asikan Log dan pel X-Ray acakan untuk pemecahan masalah dan pengamatan
Kebijakan Kontrol Versi - Simpan kebijakan Cedar dalam kontrol versi bersama kode infrastruktur
Gunakan Tag Sumber Daya - Terapkan tag untuk mengatur dan mengelola Amazon Bedrock AgentCore Gateway dan Kebijakan di AgentCore sumber daya
Audit Keamanan Reguler - Tinjau kebijakan IAM secara berkala untuk memastikan mereka mengikuti prinsip-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