我把同一個 MCP 伺服器映像部署成兩個 Bedrock AgentCore Runtime — 其他 AWS 帳戶用 SigV4,使用者用 Entra ID 認證
我把同一個 MCP 伺服器映像部署成兩個 Bedrock AgentCore Runtime。跨帳戶的呼叫端用 IAM SigV4 搭配資源型政策,使用者則透過以 Entra ID JWT 認證的 Runtime 呼叫。

本頁目錄
引言
我在 Amazon Bedrock AgentCore Runtime 上運行了一個 MCP 伺服器。第一個使用這個伺服器的 AI 代理,位在另一個 AWS 帳戶。那個 AI 代理的 ECS 任務嘗試連線時,既連不到簽發 token 的 Amazon Cognito 網域,也連不到 AgentCore 的端點。原因很可能是一個依目的地封鎖流量的對外連線過濾器。
在對外連線過濾器裡加上兩個主機,確實能讓這個 AI 代理通過,但其他呼叫端還是會遇到同樣的問題。Cognito 的 token 端點是公開的 Web 網域,沒有 PrivateLink,所以每次取得 token 的請求都會離開呼叫端的 VPC。
我把原本以 Cognito JWT 認證的 Runtime 改成了 IAM SigV4 認證,並用同一個映像另外部署了一個以 Entra ID 認證的 Runtime。這樣一來,其他 AWS 帳戶只要呼叫 IAM 版 Runtime 的 AWS 主機名稱即可。流量也能透過自己帳戶裡的 VPC endpoint,不必經過網際網路。需要在使用者認證後委任執行的工具,則放在 Entra ID 版 Runtime 上。
一個映像,兩個 Runtime
同一個容器映像以兩個 AgentCore Runtime 的形式運行,而每個 Runtime 只接受一種呼叫端。IAM 版 Runtime 接受其他 AWS 帳戶的 role 送來的請求,這些請求以 AWS Signature Version 4(SigV4)簽章。Entra ID 版 Runtime 則接受使用者的 MCP 用戶端送來的 Microsoft Entra ID 存取 token。
兩個 Runtime 來自同一條 CI 工作流、同一個映像標籤,以及同一個 Terraform 模組。容器內部唯一的差異是環境變數 AUTH_MODE。IAM 版 Runtime 把 AUTH_MODE 設為 iam,註冊共用工具。Entra ID 版 Runtime 把 AUTH_MODE 設為 entra,除了共用工具,還會註冊使用者專屬工具,也就是代表使用者登入後委任執行的工具,例如讀取使用者的個人資料。
Cognito 的 token 端點只能經由公開網際網路連線
呼叫 AgentCore Runtime 時的認證方式有兩種。一種是由自訂 JWT authorizer 檢查的 JWT,另一種是 IAM SigV4。在 Runtime 上設定 authorizer_configuration 就會使用 JWT。不設定就會使用 SigV4,也就是預設值。
使用 JWT 搭配 Cognito 時,呼叫端需要連到兩個目的地。先用 client_credentials 授權類型向 Cognito 託管網域 <your-domain>.auth.<region>.amazoncognito.com 取得 token,再帶著這個 token 呼叫 AgentCore。
Cognito 託管網域是 Web 服務,而不是 AWS API 端點,所以沒有任何 VPC endpoint 能連到它。Cognito 雖然有 VPC endpoint,但不包括 Cognito 簽發 token 的託管網域。Cognito 的 PrivateLink 說明頁面也寫明,用 client credentials 授權取得 token 不支援 PrivateLink,使用者集區的網域只能經由公開網際網路連線。因此使用 JWT 的呼叫端,必須要有一條通往公開網際網路的路由。
改用 SigV4 就不需要取得 token。呼叫端用自己的 IAM 憑證為每個請求簽章,所以呼叫端只需要連到 bedrock-agentcore.<region>.amazonaws.com 就好。AgentCore 為 bedrock-agentcore 主機提供了介面 VPC endpoint com.amazonaws.<region>.bedrock-agentcore。呼叫端的帳戶建立這個 endpoint 後,就能讓流量留在自己的 VPC 內。
我從原本的 Runtime 移除了 authorizer_configuration,讓認證方式從 JWT 變成 SigV4。
在 Runtime 和它的端點上都附加資源型政策
如果要讓另一個帳戶的 role 呼叫 Runtime,Runtime 上的資源型政策就必須列出這個 role。跨帳戶時,只靠呼叫端自己的 IAM policy 並不夠。
AgentCore 會分別檢查兩個資源是否允許 InvokeAgentRuntime:Runtime 本身,以及 Runtime 的 DEFAULT 端點。Runtime 和 DEFAULT 端點各自需要一份政策。如果只在 Runtime 上附加政策,呼叫會以 403 失敗,而且從這個 403 完全看不出是 Runtime 還是 DEFAULT 端點拒絕了請求。
CreateAgentRuntime 會自行建立 DEFAULT 端點,所以我的 Terraform 從未宣告它。DEFAULT 端點的 ARN,是在 Runtime 的 ARN 後面加上 /runtime-endpoint/DEFAULT。我組出了這兩個 ARN,並分別附加一份政策:
locals { agentcore_policy_targets = ( var.exists_ecr_images && var.authorizer == null && length(var.invoker_principal_arns) > 0 ) ? { runtime = aws_bedrockagentcore_agent_runtime.this[0].agent_runtime_arn endpoint = "${aws_bedrockagentcore_agent_runtime.this[0].agent_runtime_arn}/runtime-endpoint/DEFAULT" } : {}}
data "aws_iam_policy_document" "agentcore_invoke" { for_each = local.agentcore_policy_targets statement { sid = "AllowCrossAccountInvoke" effect = "Allow" principals { type = "AWS" identifiers = var.invoker_principal_arns } actions = ["bedrock-agentcore:InvokeAgentRuntime"] resources = [each.value] }}
resource "aws_bedrockagentcore_resource_policy" "invoke" { for_each = local.agentcore_policy_targets resource_arn = each.value policy = data.aws_iam_policy_document.agentcore_invoke[each.key].json}for_each 會依照 map 裡的每個項目各建立一份區塊。這裡的 map 有 runtime 和 endpoint 兩個項目,而資料來源和資源使用同一個 for_each,所以附加到 Runtime 的政策寫的是 Runtime 的 ARN,附加到 DEFAULT 端點的政策寫的是 DEFAULT 端點的 ARN。
在附加於 role 的 policy 裡,* 代表所有資源。資源型政策則是直接存放在資源上:S3 透過 PutBucketPolicy,AgentCore 透過 PutResourcePolicy。因此 S3 會把 * 解讀為存放政策的 bucket。AgentCore 雖然也把政策存放在資源上,Resource 仍然必須寫出存放政策的資源 ARN。Terraform 為 DEFAULT 端點產生的政策如下:
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:role/caller-agent" }, "Action": "bedrock-agentcore:InvokeAgentRuntime", "Resource": "arn:aws:bedrock-agentcore:us-east-1:111122223333:runtime/mcp_server-AbCdEf1234/runtime-endpoint/DEFAULT"}允許呼叫 Runtime 的呼叫端,列在模組的 Terraform 變數 invoker_principal_arns 裡,資源型政策的 Principal 就是從 invoker_principal_arns 產生的。invoker_principal_arns 只接受 role 或使用者的 ARN。變數驗證會拒絕帳戶的 root,例如 arn:aws:iam::111122223333:root。這是因為如果允許 root 的話,root 所屬帳戶裡的所有主體都能呼叫 Runtime。
跨 AWS 帳戶呼叫 Runtime 時必須通過的 3 個地方
跨 AWS 帳戶呼叫只有在 IAM policy 和資源型政策都允許、而且沒有被任何限制擋下時才會成功,只要 3 個地方中有任何一個不通過就會回傳 403。
- 呼叫端的 IAM policy:必須允許對 Runtime 的 ARN 和
<runtime-arn>/runtime-endpoint/*執行bedrock-agentcore:InvokeAgentRuntime。和資源型政策一樣,IAM policy 也必須同時列出 Runtime 和端點,只列出 Runtime ARN 的 policy 會被拒絕。 - 呼叫端的限制檢查:呼叫端的 permissions boundary 和 VPC endpoint policy 不能擋下跨帳戶呼叫。permissions boundary 是權限的上限,所以 permissions boundary 沒有列出的動作,不論 role 自己的 policy 怎麼定義都會被拒絕。VPC endpoint policy 則可以限制哪些主體能夠通過 VPC endpoint,所以如果 VPC endpoint policy 沒有列出呼叫端的 role,呼叫就會在 VPC endpoint 被擋下。
- 伺服器端的資源型政策:Runtime 和
DEFAULT端點上的資源型政策都必須列出呼叫端的 role。
呼叫端附加到 role 上的 IAM policy(第 1 項)寫法如下:
data "aws_iam_policy_document" "mcp_server_invoke" { statement { effect = "Allow" actions = ["bedrock-agentcore:InvokeAgentRuntime"] resources = [ var.mcp_server_runtime_arn, "${var.mcp_server_runtime_arn}/runtime-endpoint/*", ] }}3 個地方中只要有一個不通過就會回傳 403,因此兩個帳戶的部署順序也很重要。先在伺服器端套用資源型政策,再讓呼叫端指向 Runtime。順序反過來的話,在伺服器端套用資源型政策之前,呼叫端的每次呼叫都會回傳 403。
為什麼只把 Content-Type 交給簽章器?
呼叫端以服務名稱 bedrock-agentcore 簽章,而且只把 Content-Type 這個 header 交給 botocore。botocore 會把 Content-Type 和 botocore 自行加上的 host、X-Amz-* header 一起簽章。AgentCore 的 API 依用途使用 2 個不同的服務名稱簽章:
bedrock-agentcore-control:CreateAgentRuntime這類建立、管理 Runtime 的 API。bedrock-agentcore:呼叫 Runtime 的InvokeAgentRuntime,也就是本文呼叫端使用的服務名稱。
之所以只把 Content-Type 交給 botocore,是因為 httpx 或代理伺服器可能在簽章之後改寫其他 header。如果把 httpx 的所有 header 都交給 botocore,accept-encoding 這類 header 也會被納入簽章,一旦簽章後被改寫,簽章就會失效。而這樣產生的 403 看起來和缺少權限一模一樣,無法分辨。
MCP Python SDK 透過 httpx(Python 的 HTTP 用戶端)送出請求,所以簽章器是一個 httpx.Auth,也就是 httpx 在送出每個請求前執行的認證處理。簽章器把請求複製成 botocore(AWS SDK for Python 底層的函式庫)的 AWSRequest 並完成簽章,然後只把 botocore 加上的 header 寫回 httpx 的請求:
class _SigV4Auth(httpx.Auth): # botocore 會對 body 計算雜湊,所以 httpx 必須在 auth_flow 執行前先把 body 緩衝起來。 requires_request_body = True
def auth_flow(self, request): aws_request = AWSRequest( method=request.method, url=str(request.url), data=request.content, headers={ "Content-Type": request.headers.get("content-type", "application/json"), }, ) frozen = credentials.get_frozen_credentials() SigV4Auth(frozen, "bedrock-agentcore", region).add_auth(aws_request) request.headers.update(signed_headers(dict(aws_request.headers))) yield request- 緩衝 body:
requires_request_body = True讓 httpx 在auth_flow執行前先把 body 讀進記憶體。botocore 要對 body 計算雜湊,所以必須先拿到完整的 body。 - 只複製
Content-Type:建立AWSRequest時只放入Content-Type和 body,httpx 的其他 header 不會被納入簽章。 - 取得一致的憑證:ECS 任務 role 的臨時憑證會定期更新。
get_frozen_credentials()會在每次請求時取一份一致的快照,這樣一來,存取金鑰和 session token 就不會分別來自更新前後的兩組憑證,簽章也不會因為兩者不成對而失敗。 - 以
bedrock-agentcore簽章:SigV4Auth以服務名稱bedrock-agentcore簽章,並在AWSRequest上加上Authorization和X-Amz-*header。 - 只寫回簽章用的 header:
signed_headers()只保留Authorization和X-Amz-*header,其餘全部捨棄,再寫回 httpx 的請求。
給 Entra ID 使用者的第二個 Runtime
SigV4 識別的是 IAM role,而不是某個人,所以 IAM 版 Runtime 上的每個請求,看起來都來自同一個呼叫端。使用者專屬工具需要知道是哪位使用者在呼叫,而 Entra ID 存取 token 帶有使用者的身分。每個 Runtime 只接受一種認證方式,所以使用者專屬工具需要第二個 Runtime。
我用同一個映像新增了第二個 Runtime,做法是在 Terraform 裡再加一個引用同一個模組的 module 區塊。模組接受一個選用的 authorizer 物件,只有 Entra ID 版的 module 區塊會傳入 authorizer:
module "compute" { source = "../../modules/agentcore_runtime" runtime_name = local.runtime_name image_tag = var.image_tag invoker_principal_arns = local.invoker_principal_arns environment_variables = local.runtime_environment_variables # AUTH_MODE = "iam"}
module "compute_entra" { source = "../../modules/agentcore_runtime" runtime_name = local.entra_runtime_name image_tag = var.image_tag authorizer = { discovery_url = "https://login.microsoftonline.com/${local.entra_tenant_id}/v2.0/.well-known/openid-configuration" allowed_audience = local.entra_audience allowed_scopes = ["invoke"] } environment_variables = local.entra_environment_variables # AUTH_MODE = "entra"}傳入 authorizer 後,模組內部會:
- 填入
authorizer_configuration - 用
request_header_allowlist把Authorizationheader 轉送給容器,讓容器能夠讀取使用者的宣告 - 不建立資源型政策,因為使用 JWT 認證的 Runtime 完全無法用 SigV4 呼叫
我沒有更動既有的 module "compute" 位址(Terraform 在 state 裡追蹤這組資源所用的名稱)和 runtime_name。這是因為換一個新的 runtime_name 會取代整個 Runtime,而新的 Runtime 會拿到新的 ARN。呼叫端的 IAM policy 和伺服器端的資源型政策寫的都是舊的 ARN,所以兩邊都得改寫,否則呼叫會被拒絕。
| 做法 | 實際長什麼樣子 | 會重複的東西 |
|---|---|---|
| 另開一個環境目錄 | 在 environments/ 底下再建一個目錄,例如 environments/dev-entra/,裡面有自己的 Terraform 設定 | secret、ECR 設定、CI job |
| 另開一個應用程式目錄 | 把 MCP 伺服器的程式碼複製成第二份,各自建置成映像 | 共用工具的程式碼,兩份會逐漸不一致 |
兩個 module 區塊(採用) | 在同一個 environments/dev/main.tf 裡寫兩個 module 區塊,source 都指向同一個模組 | 無 |
所以最終我改用兩個引用同一個模組的 module 區塊。兩個 Runtime 位在同一個 VPC,需要的網路規則也相同,所以共用同一個 security group。
用 AUTH_MODE 只在 Entra ID 版 Runtime 上註冊使用者專屬工具
伺服器註冊的每個工具都會出現在 tools/list(MCP 用戶端取得工具清單的請求)的回應裡,而模型可以挑選清單上的任何工具。伺服器從未註冊的工具不可能被挑中,所以 IAM 版 Runtime 完全不註冊使用者專屬工具:
# AUTH_MODE 未設定或值無法辨識時一律當作 "iam",這樣缺值或打錯字時,# 會安全地退回沒有使用者專屬工具的 Runtime(fail closed),# 而不會誤開放使用者專屬工具。AUTH_MODE = os.getenv("AUTH_MODE", "iam")
if AUTH_MODE == "entra": tools_user.register(mcp)AUTH_MODE 缺少或拼錯時,容器會以 IAM 版 Runtime 的設定運行,不註冊使用者專屬工具。回報伺服器狀態的診斷工具也會回報 auth_mode。兩個 Runtime 運行的是同一個映像,所以使用者專屬工具不見時,排查的人要靠 auth_mode 才能分辨是呼叫錯了 Runtime,還是 AUTH_MODE 設錯了。
AgentCore 的 JWT authorizer 檢查完之後,容器還需要檢查什麼?
AgentCore 的 authorizer 會在請求送到容器之前,驗證 token 的簽章、有效期限、audience 和權限範圍。token 的 scp 宣告會列出 token 取得的權限範圍,例如 invoke User.Read。如果 scp 裡沒有 invoke,allowed_scopes = ["invoke"] 就會讓 authorizer 拒絕請求。
AgentCore 也會用 allowed_scopes 填入兩個地方:
- Runtime 的 OAuth 受保護資源中繼資料(MCP 用戶端用來查詢要向哪裡取得 token 的文件)裡的
scopes_supported - 401 回應的
WWW-Authenticateheader 裡的權限範圍
MCP 用戶端就是從 scopes_supported 和 WWW-Authenticate 得知要請求哪個權限範圍。
Entra ID v2 token 在 scp 裡放的是單純的權限範圍名稱,所以 allowed_scopes 要寫 invoke,而不是 api://<client-id>/…/invoke。
authorizer 不會比對 tid 和 iss 的值,也不會檢查 scp 是否存在,所以容器會在每次呼叫使用者專屬工具時自行檢查。token 已經驗證過,所以容器只需要把 payload 做 base64url 解碼:
if not expected_tenant or str(tid).lower() != expected_tenant.lower(): raise AuthError("tenant mismatch")
expected_issuer = f"https://login.microsoftonline.com/{expected_tenant}/v2.0"if str(payload.get("iss", "")).lower() != expected_issuer.lower(): raise AuthError("issuer mismatch")
if not payload.get("scp"): raise AuthError("token has no scp claim: app-only (client_credentials) tokens cannot use user-specific tools")- 租用戶:
tid必須和預期的租用戶 ID 一致,沒有設定預期的租用戶時也一律拒絕。錯誤訊息不會寫出任何租用戶 ID,因此無法被拿來推測租用戶 ID。 - 簽發者:
iss必須是https://login.microsoftonline.com/<租用戶 ID>/v2.0,也就是預期租用戶的 v2 簽發者。 scp是否存在:透過client_credentials授權取得的僅限應用程式 token 沒有scp。這項檢查堵住了一條繞過使用者的路,CI 的身分無法呼叫讀取個人資料的工具。
總結
我把 MCP 伺服器從 Cognito JWT 改成了 IAM SigV4,讓另一個 AWS 帳戶的呼叫端只需要呼叫一個 AWS 主機名稱,而且可以透過自己帳戶裡的 VPC endpoint 呼叫。接著我用同一個映像新增了一個 Entra ID 版 Runtime,因為 SigV4 識別的是 role,而使用者專屬工具需要知道是哪位使用者在呼叫。
- 不設定
authorizer_configuration就會使用 SigV4。AgentCore 的每個 Runtime 只能使用 SigV4 或 JWT 其中之一,不能兩者並用。 - 在 Runtime 和
<runtime-arn>/runtime-endpoint/DEFAULT上各附加一份資源型政策,各自寫明所附加資源的確切 ARN。 - 允許呼叫端對 Runtime 和
/runtime-endpoint/*執行InvokeAgentRuntime,並檢查呼叫端的 permissions boundary 和 VPC endpoint policy,因為 3 個地方中任何一個不通過就會回傳 403。 - 以
bedrock-agentcore簽章,並且只把Content-Type交給 botocore。 - 只在 Entra ID 版 Runtime 上註冊使用者專屬工具,並讓
AUTH_MODE預設為不註冊這些工具的iam。 - 在容器裡比對
tid和iss的值,並檢查scp是否存在,因為 AgentCore 的 authorizer 只檢查簽章、有效期限、audience 和權限範圍。



