概要ゲートウェイ実行ロールリソース管理ロールロールの更新が必要なのはいつですか?トラブルシューティング例: 両方の IAM ロールの作成ベストプラクティス

AgentCore IAM アクセス許可の AgentCore ゲートウェイとポリシー

このガイドでは、Cedar ポリシーを使用したきめ細かな認可制御のために、Amazon Bedrock AgentCore Gateway を AgentCore のポリシーで使用するために必要な IAM アクセス許可を提供します。

概要

Amazon Bedrock AgentCore Gateway を AgentCore のポリシーと統合する場合、2 つの異なる IAM ロールが必要です。

ゲートウェイ実行ロール - ターゲットを呼び出して Cedar ポリシーを評価するために Amazon Bedrock AgentCore Gateway が実行時に引き受ける IAM ロール
リソース管理ロール - 管理者が AgentCore リソースで Amazon Bedrock AgentCore Gateway とポリシーを作成および管理するために使用する IAM AgentCore ロール

どちらのロールも異なる目的を果たし、特定のアクセス許可を必要とします。ゲートウェイ実行ロールには Amazon Bedrock AgentCore Gateway オペレーションを実行するアクセス許可が必要ですが、リソース管理ロールには AgentCore リソースで Amazon Bedrock AgentCore Gateway とポリシーを設定および管理するためのアクセス許可が必要です。

ゲートウェイ実行ロール

ゲートウェイ実行ロールは、リクエストを処理するときに Amazon Bedrock AgentCore Gateway サービスによって引き受けられます。このロールには、次のアクセス許可が必要です。

AgentCore の Policy を使用して Cedar ポリシーを評価する
Lambda 関数や API Gateway エンドポイントなどのターゲットを呼び出す
CloudWatch と X-Ray にログとトレースを書き込む
認証設定のアクセスシークレット

重要

AgentCore のポリシーで Amazon Bedrock AgentCoreGateway を使用するには、実行ロールに次の 3 つのアクセス許可を含める必要があります。 bedrock-agentcore:AuthorizeAction- 認可決定の Cedar ポリシーを評価します。 bedrock-agentcore:PartiallyAuthorizeActions- 呼び出し元がを呼び出すことを許可されているツールを一覧表示します。 bedrock-agentcore:GetPolicyEngine- ポリシーエンジン設定を取得します。これらのアクセス許可がないと、ゲートウェイはポリシー認可を実行できません。このマニフェストは、既存のゲートウェイにポリシーエンジンをアタッチすると InternalServerException が発生し、許可ポリシーが設定されていても、デフォルトですべてのツール呼び出しが拒否されます。

信頼ポリシー

ゲートウェイ実行ロールは、bedrock-agentcore.amazonaws.comサービスプリンシパルを信頼する必要があります。

重要

次のプレースホルダーを置き換えます。

us-east-1 と AWS リージョン
123456789012 と AWS アカウント ID


{
"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:*"
        }
      }
    }
  ]
}

アクセス許可ポリシー

このポリシーは、Amazon Bedrock AgentCore Gateway に AgentCore の Policy を通じて Cedar ポリシーを評価するために必要なアクセス許可を付与します AgentCore 。アクセス許可は、最小特権の原則に従って 2 つのステートメントに分割されます。

重要

これらのプレースホルダーを置き換えます。

us-east-1 と AWS リージョン
123456789012 と AWS アカウント ID
ゲートウェイ ID が <gateway-id>、またはすべてのゲートウェイが *
ポリシーエンジン ID が <policy-engine-id>、またはすべてのポリシーエンジンが *


{
"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>"
      ]
    }
  ]
}

注記

ゲートウェイターゲットには、これらに加えて独自のアクセス許可が必要であり、ターゲットタイプによって異なります。各タイプに必要なアクセス許可については、AWS 「リソースへのアクセス許可」を参照してください。
本番環境では、プレースホルダーを policy-engine/my_policy_engine-a1b2c3d4e5の代わりに特定のリソース IDs に置き換えてpolicy-engine/<policy-engine-id>、最小特権の原則に従います。ワイルドカード ( * ) は、そのタイプのすべてのリソースを許可する場合にのみ使用します。

一時ポリシーの IAM アクセス許可

一時ポリシーでは、Gateway がワークロードアクセストークン (WAT) をマイニングすることで、呼び出し元のセッション ID をリクエスト全体に伝達する必要があります。 AWS IAM インバウンドフローでは、このミントはを呼び出しますGetWorkloadAccessToken。Gateway のワークロード ID ディレクトリにbedrock-agentcore:GetWorkloadAccessTokenスコープされたゲートウェイ実行ロールを付与します。このページで既に説明されている 3 つのポリシーアクセス許可 (AuthorizeAction、、GetPolicyEngine) に加えてPartiallyAuthorizeActions、このアクセス許可を追加します。このアクセス許可は、一時ポリシーがアクティブ (ポリシーセッション ID が指定され、ポリシーエンジンがアタッチされている) の場合にのみ必要です。一時ポリシーが無効になっている場合は必須ではありません。

ゲートウェイ実行ロールのアクセス許可ポリシーに次のステートメントを追加します。


{
  "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>*"
  ]
}

このアクセス許可がないと、一時ポリシーが有効になると、ツールの呼び出しは token-mint ステップ (AccessDenied の GetWorkloadAccessToken) で失敗します。本番環境では、を特定のゲートウェイ ID <gatewayId>に置き換えて、最小特権の原則に従います。

一時的なポリシーに関する考慮事項におけるこの要件の概要については、「必要な IAM アクセス許可」を参照してください。

リソース管理ロール

リソース管理ロールは、管理者が AgentCore リソースで Amazon Bedrock AgentCore Gateway とポリシーを作成および管理するために使用します。このロールには、次のアクセス許可が必要です。

重要

リストに加えて 4 つのサマリーアクションを付与し、アクション ListPolicyEngineSummaries、GetPolicyEngineSummary、ListPolicySummaries、を取得しますGetPolicySummary。これらのアクションにより、カスタマーマネージドキーが使用できないときに、ポリシーエンジンとポリシーを列挙できます。事前に付与することで、復旧が可能になります。詳細については、「使用不可のキー」を参照してください。ポリシーを一覧表示または読み取ることはできません。

AgentCore へのフルアクセスを許可するマネージドポリシーについては、AWS 「Amazon Bedrock AgentCore のマネージドポリシー」を参照してください。暗号化されたポリシーエンジンが追加で必要とする AWS KMS アクセス許可については、「ポリシーエンジンの暗号化をカスタマイズする」を参照してください。

ゲートウェイとゲートウェイターゲットの作成、更新、削除
ポリシーエンジンと Cedar ポリシーの作成、更新、削除
ポリシーの作成時にゲートウェイを呼び出し (InvokeGateway)、AgentCore のポリシーがターゲットゲートウェイの機能に対して Cedar ステートメントのアクションを検証できるようにします。
作成時にゲートウェイ実行ロールを Amazon Bedrock AgentCore Gateway リソースに渡す
組織と管理のリソースにタグを付ける
IAM ロール情報を読み取り、実行ロール設定を検証する

このロールはゲートウェイ実行ロールとは別に、AgentCore 設定で Amazon Bedrock AgentCore Gateway とポリシーを設定または変更する場合にのみ必要です。

アクセス許可ポリシー

重要

これらのプレースホルダーを置き換えます。

us-east-1 と AWS リージョン
123456789012 と AWS アカウント ID


{
"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",
        "bedrock-agentcore:ListPolicyEngineSummaries",
        "bedrock-agentcore:GetPolicyEngineSummary"
      ],
      "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",
        "bedrock-agentcore:ListPolicySummaries",
        "bedrock-agentcore:GetPolicySummary"
      ],
      "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/*"
      ]
    }
  ]
}

重要

bedrock-agentcore:InvokeGateway は、実行時に Gateway を呼び出すだけでなく、Cedar ポリシーを作成または更新するために必要です。 CreatePolicyおよび Cedar ステートメントのアクションを Gateway に対してUpdatePolicy検証します。これは、Gateway ARN InvokeGatewayでとして承認されたオペレーションです。これがないと、ポリシーは CREATE_FAILEDを使用してに移行しますInsufficient permissions to call gateway with ID <gateway-id>。

重要

ManageResourceScopedPolicy および ManageAdminPolicyアクションは、管理者が作成できる Cedar ポリシーのタイプを制御するアクセス許可のみのゲートです。* ManageResourceScopedPolicy - 特定のゲートウェイ ARNs をターゲットとする Cedar ポリシーを作成するアクセス許可 ( に適用されるポリシーなどgateway/my-gateway-123) * ManageAdminPolicy - ワイルドカードを使用して Cedar ポリシーを作成するアクセス許可 (ゲートウェイ/* に適用されるポリシーなど) を付与します。両方のアクセス許可は、完全なポリシー管理機能に必要です。これらは API オペレーションではなく、ポリシー管理 APIs。

注記

リソースフィールドは整合性のために含まれていますが、これらのアクセス許可のみのアクションは、主にリソースレベルではなくアクションレベルで機能をゲートします。

ロールの更新が必要なのはいつですか?

Amazon Bedrock AgentCore Gateway の作成方法に基づいて、Amazon Bedrock AgentCore Gateway 実行ロールに AgentCore アクセス許可のポリシーを追加する必要があるかどうかを確認します。

シナリオ 1: AgentCore CLI で作成されたゲートウェイ

ステータス: 必要なアクション

AgentCore CLI は、ターゲット呼び出しとアウトバウンド認証のスコープ付きアクセス許可を持つゲートウェイ実行ロールを作成しますが、AgentCore アクセス許可にポリシーは含まれません。このガイドに記載されている AuthorizeAction 、、および PartiallyAuthorizeActions アクセスGetPolicyEngine許可をゲートウェイ実行ロールに手動で追加する必要があります。

シナリオ 2: カスタム実行ロール

ステータス: 必要なアクション

カスタム IAM ロールでは、このガイドに記載されている AgentCore のポリシーを手動で追加する必要があります。上記のセクションのアクセス許可ポリシーに従います。

シナリオ 3: 本番稼働用最小特権設定

ステータス: 必要なアクション

本番環境では、ワイルドカードを使用するのではなく、特定のリソース ARNs に AgentCore アクセス許可のポリシーをスコープします。policy-engine/* と gateway/* を、アクセス許可ポリシー内の特定のポリシーエンジンとゲートウェイ IDsに置き換えます。

トラブルシューティング

このセクションでは、Amazon Bedrock AgentCore Gateway の IAM アクセス許可を AgentCore のポリシーで設定する際の一般的な問題について説明します AgentCore 。

ポリシー評価中の InternalServerException

症状: ポリシーエンジンを既存のゲートウェイにアタッチInternalServerException - Policy evaluation failedすると、ゲートウェイはを返し、許可ポリシーが設定されていても、すべてのツール呼び出しはデフォルトで拒否されます。

根本原因: ゲートウェイ実行ロールに AgentCore アクセス許可に必要なポリシーがありません。これらのアクセス許可がないと、ゲートウェイはポリシー認可を実行できません。

解決策: ゲートウェイ実行ロールに次の 3 つのアクセス許可が含まれていることを確認します。


{
  "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/*"
  ]
}

注記

Policy Engine コンソールを使用して既存のゲートウェイに Policy Engine をアタッチすると、IAM アクセス許可が自動的に更新されない場合があります。これらのアクセス許可は、ゲートウェイのサービスにリンクされたロールに手動で追加する必要があります。

CreatePolicy での「ゲートウェイを呼び出すためのアクセス許可が不十分」

症状: は CreatePolicyを返しますがpolicyId、ゲートウェイ実行ロールに AuthorizeAction、、がある場合Insufficient permissions to call gateway with ID <gateway-id>でもPartiallyAuthorizeActions、ポリシーは CREATE_FAILEDでに移行しますGetPolicyEngine。

根本原因: ギャップは、ゲートウェイ実行ロールではなくCreatePolicy、を呼び出すリソース管理ロールにあります。ポリシー検証は Gateway ( として認可bedrock-agentcore:InvokeGateway) を呼び出します。エラー名は Gateway ですが、修正はポリシー作成ロールにあります。

解決策: bedrock-agentcore:InvokeGateway (ゲートウェイ ARN の範囲) をリソース管理ロールに追加します。


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

LOG_ONLY モードでのサイレント障害

症状: ポリシーエンジンは LOG_ONLY モードで機能しているように見えますが、適切なエラーメッセージなしでサイレントに失敗します。

根本原因: アクセスbedrock-agentcore:GetPolicyEngine許可がないと、ENFORCED モードに切り替えるときにのみ発生するサイレント障害が発生します。

解決策: テストbedrock-agentcore:GetPolicyEngineに LOG_ONLY モードを使用している場合でも、常にゲートウェイ実行ロールにを含めます。

ポリシーエンジンが見つかりませんエラー

症状: Amazon Bedrock AgentCore Gateway は、ポリシーエンジンを見つけられない、またはアクセスできないことを示すエラーを返します。

根本原因: ゲートウェイ実行ロールのポリシーが誤った ARN パターンを使用しているか、ポリシーエンジンリソースがありません。

解決策: ポリシーエンジンとゲートウェイの両方の ARNs がリソース配列に含まれていることを確認します。


"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>"
]

注記

AuthorizeAction との両方には、ポリシーエンジンとゲートウェイリソースの両方へのアクセスPartiallyAuthorizeActionsが必要です。

デバッグのヒント

CloudWatch Logs を有効にする - ポリシー評価の詳細をキャプチャするように Amazon Bedrock AgentCore Gateway の詳細ログ記録を設定する
X-Ray トレースの確認 - AWS X-Ray トレースをチェックして、認可チェックが失敗した場所を特定する
LOG_ONLY モードから開始 - 最初に LOG_ONLY モードを使用して、リクエストをブロックせずに Cedar ポリシーをテストします。
4 つのアクセス許可をすべて検証する - AuthorizeAction 、、および PartiallyAuthorizeActions GetPolicyEngineがすべて存在することを確認します
ENFORCED モードに切り替える - LOG_ONLY モードですべてのアクセス許可が機能することを確認した後にのみ、ENFORCED モードに切り替えます。

例: 両方の IAM ロールの作成

次の例は、 CLI を使用して両方の必要な IAM AWS ロールを作成する方法を示しています。

ステップ 1: ゲートウェイ実行ロールを作成する


# 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

ステップ 2: ゲートウェイ実行ロールにアクセス許可をアタッチする


# 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

注記

この例では、AgentCore のアクセス許可のポリシーのみを示しています。Amazon Bedrock AgentCore Gateway ターゲット (Lambda、API Gateway など) に対する追加のアクセス許可は、特定の統合要件に基づいて追加する必要があります。

ステップ 3: 次のステップ

AgentCore で必要なポリシーのアクセス許可を使用して実行ロールを設定したら、ポリシーリソースの作成と設定に進みます。詳細なガイダンスについては、以下を参照してください。

ポリシーエンジンの作成 - 「ポリシーエンジンの作成」を参照してください。
Cedar ポリシーの記述 - Cedar ポリシー言語リファレンスを参照してください。

ベストプラクティス

個別のロールを使用する - Amazon Bedrock AgentCore Gateway の実行とリソース管理の個別のロールを維持する
最小特権の適用 - 本番稼働用のワイルドカードではなく、特定のリソース ARNs から開始します。
LOG_ONLY モードでテストする - ポリシーを適用する前に、必ず LOG_ONLY モードでポリシーエンジンの統合をテストします。
モニタリングを有効にする - トラブルシューティングとオブザーバビリティのために CloudWatch Logs と X-Ray トレースを設定する
バージョン管理ポリシー - Cedar ポリシーをインフラストラクチャコードとともにバージョン管理に保存する
リソースタグを使用する - タグを適用して、AgentCore リソースの Amazon Bedrock AgentCore Gateway とポリシーを整理および管理します
定期的なセキュリティ監査 - IAM ポリシーを定期的に見直して、最小特権の原則に従っていることを確認します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

重要な概念

ポリシーエンジンを作成する