[notgitika]

Description

Allow GATEWAY_IAM_ROLE outbound authentication for mcpServer and openApiSchema project Gateway targets.

This change:

• extends the existing target authentication matrix for MCP Server and OpenAPI targets
• requires the SigV4 service for configured IAM role authentication while keeping region optional
• rejects IAM signing fields on non-IAM outbound authentication configurations
• reuses the existing --target-configuration JSON/file input instead of adding --signing-service or --signing-region flags

A companion AgentCore CDK change is still required to synthesize the configured IAM credential provider for these target types.

Related Issue

Part of #2245

Documentation PR

Not applicable. This uses the existing --target-configuration interface and introduces no new CLI flags.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran bun test — 4,702 passed, 6 skipped, 0 failed
• I ran an account-level end-to-end test in us-west-2
  • confirmed both IAM target shapes are accepted through --target-configuration
  • reproduced the expected synth failure with the currently pinned @aws/agentcore-cdk@1.0.0
  • used a local companion CDK implementation to deploy OpenAPI and MCP Server targets; both reached READY
  • verified the MCP backend denied anonymous requests with 403, while AgentCore completed IAM-signed tool discovery
  • deleted the disposable stacks, log group, Gateway resources, IAM resources, and CDK asset object versions afterward
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check
• I ran bun run build
• If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them — src/assets/ was not modified

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly — no documentation changes are needed for the existing generic JSON interface
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[github-actions]

Package Tarball

aws-agentcore-1.0.1.tgz

How to install

gh release download pr-2720-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-1.0.1.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.54%. Comparing base (5febc10) to head (b509345).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2720   +/-   ##
=========================================
  Coverage     96.54%   96.54%           
=========================================
  Files           706      706           
  Lines         58529    58543   +14     
=========================================
+ Hits          56508    56522   +14     
  Misses         2021     2021           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Changes requested

Base branch confirmed as refactor; reviewed against it. The schema change itself is well-shaped and matches the service contract (AWS::BedrockAgentCore::GatewayTarget IamCredentialProvider has a required Service and an optional Region that defaults to the gateway's region), and the tests use the real temp-project harness rather than fs mocks. One blocking problem, though: the CLI would start accepting a project spec that the pinned CDK library cannot deploy.

Blocking: pinned @aws/agentcore-cdk@1.0.0 rejects these specs, breaking agentcore deploy for the whole project

src/assets/cdk/package.json pins "@aws/agentcore-cdk": "1.0.0", and the vended app (src/assets/cdk/bin/cdk.ts) calls readAgentCoreProject, which validates agentcore.json against the library's own copy of the schema and throws ConfigValidationError on failure (dist/cdk/project/read-project.js). In the published 1.0.0 tarball that copy still has:

// dist/schema/schemas/mcp.js
openApiSchema: { authRequired: true,  validAuthTypes: ['OAUTH', 'API_KEY'], iamRoleFallback: false },
mcpServer:     { authRequired: false, validAuthTypes: ['OAUTH', 'NONE'],    iamRoleFallback: false },
...
message: `${data.targetType} targets do not support ${authType} outbound auth`

So a target written by this PR's new code path makes synth fail with "mcpServer targets do not support GATEWAY_IAM_ROLE outbound auth" — a message that directly contradicts the CLI validation that just accepted it, and the failure is at project-spec parse time, so it takes down deployment of every resource in the project, not just that one target.

Even if that validation were bypassed, the construct still can't honor the config: AgentCoreGateway.credentialProviders() only returns a provider for OAUTH/API_KEY and then falls back to iamRoleFallback (false for both of these target types), so:

• addMcpServerTarget passes credentialProviderConfigurations: [] — the configured IAM signing is silently dropped;
• addApiSchemaTarget throws "Target ... of type openApiSchema requires outbound auth (OAUTH or API_KEY)".

The cfnCredentialProvider() branch that actually emits iamCredentialProvider: { service, region } is only reached from addL1Target (passthrough / httpRuntime / apiGateway / connector).

This matches the PR description ("a companion AgentCore CDK change is still required") and the unchecked "dependent changes have been merged and published" box. Options:

1. Land and publish the construct change first, then bump the pin in src/assets/cdk/package.json to that version as part of this PR (preferred — keeps CLI acceptance and deployability in sync).
2. Hold this PR and merge it after the construct release lands.
3. If the relaxation must land now, gate it so the CLI refuses the config (or at minimum warns loudly) when the project's pinned @aws/agentcore-cdk version predates support — otherwise users get an opaque synth failure for a config the CLI told them was valid.

Please also consider the upgrade path for already-vended projects, whose agentcore/cdk/package.json pins the older library independently of the CLI version.

Non-blocking note

IAM_SERVICE_AUTH_TARGET_TYPES (src/projectSchemas/gateway.ts:95) re-encodes information already in TARGET_TYPE_AUTH_CONFIG. If someone later adds GATEWAY_IAM_ROLE to another target type's validAuthTypes and forgets this list, the required-service check is skipped and synth emits an IamCredentialProvider without the CFN-required Service. Deriving it (TARGET_TYPE_AUTH_CONFIG[data.targetType].validAuthTypes.includes("GATEWAY_IAM_ROLE")) removes the drift risk and lets the list go away.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[notgitika]

Thanks—the deployment blocker is valid.

• The non-blocking drift concern is addressed in b509345: the service requirement is now derived from TARGET_TYPE_AUTH_CONFIG instead of a second target-type list.
• I reproduced the blocker with the generated project and pinned @aws/agentcore-cdk@1.0.0; agentcore build rejects the CLI-accepted OpenAPI IAM target.
• I then ran an account-level E2E with a local companion CDK implementation. Both the OpenAPI and MCP Server targets reached READY with GATEWAY_IAM_ROLE, service: execute-api, and region: us-west-2.
• The MCP backend required AWS_IAM and returned 403 anonymously, so successful target stabilization also exercised real SigV4-signed tool discovery.

I updated the Testing section with these results. The PR remains a draft and the dependent-change checkbox remains unchecked until the CDK support is merged, published, and the CLI pin/upgrade path is handled.